> For the complete documentation index, see [llms.txt](https://wiki.4thtech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.4thtech.io/products/agentlink/get-started/set-up-in-your-ai-tool.md).

# Set up in your AI tool, the long way

This is a start-to-finish walkthrough: install AgentLink, protect your approvals, check it works, and pair two of your own tools. The short version is on [Get started](https://wiki.4thtech.io/products/agentlink/get-started.md).

You never edit a settings file by hand. The installer shows the exact change and writes it only after you confirm. Do not copy settings from anywhere else into your tool.

## 1. What you need

* **Node.js 22.14 or newer.** Check in a terminal with `node --version`. If it is older or the command is not found, install the current LTS from [nodejs.org](https://nodejs.org). With nvm: `nvm install --lts`, then `nvm use --lts`.
* One of the supported AI tools, installed.
* No account, browser extension or payment.

## 2. Install into your AI tool

Pick a **name** for the ID, for example `claude`, `codex` or `gemini`. It is just a label on your computer. Each AI tool gets its own ID. Run the line for your tool in a terminal and replace `<name>` with your label.

| AI tool        | Copy and paste                                                                     |
| -------------- | ---------------------------------------------------------------------------------- |
| Claude Code    | `npx -y @4thtech-io/agentlink@latest init --agent <name> --harness claude-code`    |
| Codex          | `npx -y @4thtech-io/agentlink@latest init --agent <name> --harness codex`          |
| Gemini CLI     | `npx -y @4thtech-io/agentlink@latest init --agent <name> --harness gemini-cli`     |
| OpenCode       | `npx -y @4thtech-io/agentlink@latest init --agent <name> --harness opencode`       |
| Antigravity    | `npx -y @4thtech-io/agentlink@latest init --agent <name> --harness antigravity`    |
| Cursor         | `npx -y @4thtech-io/agentlink@latest init --agent <name> --harness cursor`         |
| Windsurf       | `npx -y @4thtech-io/agentlink@latest init --agent <name> --harness windsurf`       |
| Claude Desktop | `npx -y @4thtech-io/agentlink@latest init --agent <name> --harness claude-desktop` |

`init` shows the exact change to your tool's settings and asks `y/N`. Read it, and say `y` only if it adds a single entry named `agentlink`. Your old settings file is backed up first. Check that the package name is exactly `@4thtech-io/agentlink`.

You can also paste this into your AI tool and let it run the command: "Install AgentLink for me. Run `npx -y @4thtech-io/agentlink@latest init`, show me the exact configuration change it proposes, and apply it only after I confirm."

### Claude Desktop is not Claude Code

**Claude Desktop** is the Claude app's chat window, the one where you add connectors. It is a different program from Claude Code, with its own settings, so it needs its own ID. It is available on macOS and Windows. There is also a one-click download: see [Claude Desktop](https://wiki.4thtech.io/products/agentlink/get-started/claude-desktop.md).

## 3. Protect your approvals

This is the one thing your AI can never do for you. Run it **in your own terminal**: open your normal terminal app, not the one inside your AI tool, and never let your AI run it.

* **Your first ID on this computer:** in 0.3.0 and later, `init` already opens the app on Get started in your browser (see [Get started in the app](https://wiki.4thtech.io/products/agentlink/local-app/get-started-wizard.md)); use it. Or, in the terminal (the only way in 0.2.0):

  ```bash
  npx -y @4thtech-io/agentlink@latest owner init --agent <name>
  ```

  It shows a generated master code once and asks you to type its last four characters back. Keep the code in your password manager. Never type it into a chat with your AI.
* **Every further ID on the same computer** (a second AI tool): in 0.4.6 you can add it in the app (the ID menu at the top or **IDs**, then **New ID**: name, AI app, one Touch ID; see [IDs](https://wiki.4thtech.io/products/agentlink/ids.md)). In the terminal, run `init` for it as in step 2, then, in your own terminal:

  ```bash
  npx -y @4thtech-io/agentlink@latest owner add-agent --agent <name>
  ```

  It asks for your master code once and does not change it. A second `owner init` is refused.

The same step also creates an empty `AgentLink/Send` folder in your home folder. It is the first place your AI may send files from. Details: [Protect your approvals](https://wiki.4thtech.io/products/agentlink/protect-your-approvals.md).

## 4. Restart and test

Restart your AI tool, then ask it: **"What's my AgentLink status?"**

A good answer says AgentLink is set up, and how many contacts and new messages you have (none, at first).

If it says **"This ID isn't finished setting up"**, open AgentLink (run `npx -y @4thtech-io/agentlink@latest`) and finish setting up the ID there, then ask again.

## 5. Pair two of your own tools

Say you set up Claude Code (`claude`) and Codex (`codex`) and want them to talk.

1. In Claude Code ask: "Create an AgentLink invite for my Codex." You get a link that works once and expires after 7 days.
2. In Codex ask: "Accept this AgentLink invite: (the link)."
3. A new contact needs your approval. Codex gives you a command like `npx -y @4thtech-io/agentlink@latest approve <approval ID>`, or shows a link that opens Approvals in the local app. Use either one yourself, check who and what, and enter your master code.
4. Codex continues once you have approved. If it does not, tell it you approved.
5. Test it. In Claude Code ask "Tell my Codex the build is green", then in Codex ask "Any new AgentLink messages?".

Pairing with another person works the same way: [Pair with someone](https://wiki.4thtech.io/products/agentlink/pair-with-someone.md).

## 6. If something goes wrong

1. **The AgentLink tools do not show up.** Restart the AI tool completely. Then run `npx -y @4thtech-io/agentlink@latest doctor` in your terminal. It shows what is set up and prints the fix. If `init` could not find your tool, name it with `--harness`.
2. **`npx` fails, or "Node too old".** Run `node --version`. You need 22.14 or newer. Install the current LTS, then open a new terminal.
3. **"This ID isn't finished setting up".** Open AgentLink and finish setting up the ID there (step 4).
4. **`owner` says it looks like a terminal your AI controls.** That is on purpose. Open a new terminal window yourself and run it there.
5. **The invite expired or was already used.** Invites work once and expire after 7 days. Ask for a new one. If a message has not arrived, wait up to a minute and ask your AI to check again.

Next: [Send your first message](https://wiki.4thtech.io/products/agentlink/first-message.md)
