How to run Ori with Claude Code

This guide shows how to start Ori connected to Claude Code. It assumes you have already built and run Ori once (see the getting started tutorial) and that you have a working Claude account or API key.

Steps

Make sure Node.js and npm are available: the backend spawns the Claude Agent SDK's ACP adapter with npx -y @agentclientprotocol/claude-agent-acp. The adapter ships its own Claude Code CLI (a native package chosen for your platform), so it works even if the claude command on your machine is older.
Make sure Claude Code is authenticated on this machine (claude login flow, or an ANTHROPIC_API_KEY environment variable the adapter can use).
From the repository root, start the server:
```
make run
```
Open http://localhost:8888 and start prompting. Tool calls, plans and permission requests appear exactly as with the demo agent.

Variants

To work on a specific project directory, pass the agent's working directory explicitly: ./bin/ori --cwd /path/to/your/project.
To serve on another port: ./bin/ori --addr :9000.
The first npx run downloads the adapter package; pin it by installing it globally (npm install -g @agentclientprotocol/claude-agent-acp) and passing --agent-cmd "claude-agent-acp".

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


# How to run Ori with Claude Code

This guide shows how to start Ori connected to Claude Code. It assumes you have already built and run Ori once (see the [getting started tutorial](../tutorials/getting-started.md)) and that you have a working Claude account or API key.

## Steps

1. Make sure Node.js and npm are available: the backend spawns the Claude Agent SDK's ACP adapter with `npx -y @agentclientprotocol/claude-agent-acp`. The adapter ships its own Claude Code CLI (a native package chosen for your platform), so it works even if the `claude` command on your machine is older.
2. Make sure Claude Code is authenticated on this machine (`claude` login flow, or an `ANTHROPIC_API_KEY` environment variable the adapter can use).
3. From the repository root, start the server:

   ```bash
   make run
   ```

4. Open [http://localhost:8888](http://localhost:8888) and start prompting. Tool calls, plans and permission requests appear exactly as with the demo agent.

## Variants

- To work on a specific project directory, pass the agent's working directory explicitly: `./bin/ori --cwd /path/to/your/project`.
- To serve on another port: `./bin/ori --addr :9000`.
- The first `npx` run downloads the adapter package; pin it by installing it globally (`npm install -g @agentclientprotocol/claude-agent-acp`) and passing `--agent-cmd "claude-agent-acp"`.

## See also

- Flags reference: [the ori command](../reference/cli.md)
- Connecting something else than Claude: [use another ACP agent](use-another-agent.md)