# Claude Code

Claude Code runs in your terminal and connects to Catena with the
[CLI](https://docs.catena.com/connect/cli.md). The same steps work for other terminal agents, such as
Cursor's agent, OpenClaw, and Hermes.

Claude Code on the web is different, because it starts a fresh cloud sandbox for
each task. To connect it, see [Cloud coding agents](https://docs.catena.com/integrations/cloud-agents.md).

## Requirements

Before you start, you'll need:

- **Node.js:** Version 20 or later.
- **The admin role:** You need the admin role in the Catena organization the
  agent will join, or someone with that role who can approve the link.

## Connect Claude Code

1. In the repository where Claude Code works, paste this prompt:

   ```prompt
   Connect yourself to my Catena account. Install the Catena CLI with `npm i -g @catena/cli`, then run `catena guide` and follow it. Once linked, install the Catena skill so future sessions know to use the CLI: `npx -y skills add catena-labs/skills --skill catena-cli --global --yes`.
   ```

   To connect an agent you already created in the console, add
   `to link the existing agent agent_...` after `follow it`.

2. Claude Code asks for permission to run commands. Allow `npm i -g @catena/cli`
   and the `catena` commands.
3. Claude Code prints an approval link. Open it, choose the organization (live
   or sandbox) and the agent's [policy](https://docs.catena.com/policies.md), and approve.
4. Tell Claude Code you approved. It will run `catena link` again, which prints
   `Done`.

## Test the connection

To check that everything is working, ask Claude Code to run `catena whoami` and
`catena policy show`. It will report the agent's name and what its policy
allows.

## Credential storage

On macOS, the CLI stores the key in the Keychain. On Linux, it uses the Secret
Service keyring (or, when there is no keyring, a file only your user can read).
See [Credential storage](https://docs.catena.com/connect/credentials.md) for details.

## One agent per repository

`catena link` binds the current directory to the agent it links, so every Claude
Code session in that repository acts as the same agent. If you'd like to use a
different agent in another repository, we recommend linking from there with
`--profile <name>`. See [Profiles](https://docs.catena.com/connect/cli.md#profiles).

## Limitations

There are a few things to keep in mind when you use Claude Code:

- Payments at or above your approval threshold will wait for an admin. Claude
  Code reports the intent as `pending` and can give you the approval link.
- The skill tells future sessions to use the CLI, and it is the method we
  support. Do not add Catena instructions to `CLAUDE.md` in its place.

## Related

- [Link with the CLI](https://docs.catena.com/connect/cli.md): Link a new or existing agent that runs in a terminal, on your own machine or a headless host, with catena link.
- [Credential storage](https://docs.catena.com/connect/credentials.md): Where the CLI keeps an agent's signing key on each kind of host, and which credential mode to use when there's no keychain.
- [Cloud coding agents](https://docs.catena.com/integrations/cloud-agents.md): Connect Claude, Codex, and Cursor cloud agents and Copilot's coding agent to Catena with a secret key that the platform injects into each sandbox.