---
title: Setup
description: Set up Tadoru with native integration or printed instructions for manual placement.
---

Tadoru ships one canonical `skills/SKILL.md`. `tadoru setup` installs it unchanged for agents with native skill support. For opencode and pi, it derives an instruction snippet, prints it to stdout, and leaves placement to you. For MCP, setup prints the registration command to run — only Claude Desktop's config file is written directly; opencode's MCP JSON is likewise printed for manual configuration.

```bash
tadoru setup --agent <claude|codex|opencode|hermes|pi|claude-desktop> [--scope project|user] [--print]
```

| Flag | Description |
| --- | --- |
| `--agent` | Target: `claude` / `codex` / `opencode` / `hermes` / `pi` / `claude-desktop` |
| `--scope` | `project` (default; current repository) or `user` (account-wide). It has no effect on the manual opencode/pi output |
| `--print` | Preview planned file changes without writing. opencode and pi never write files, with or without this flag |

:::tip
For agents that write files, run with `--print` first to preview every file that would be created or modified.
:::

## Per-agent setup

**Claude Code**

```bash
tadoru setup --agent claude
```

This installs the canonical `SKILL.md` unchanged where Claude Code discovers skills, and prints the MCP registration command to run:

```bash
claude mcp add tadoru -- tadoru mcp
```

With `--scope user`, the skill installs for all your projects instead of the current repository.

**Codex CLI**

```bash
tadoru setup --agent codex
```

Installs the canonical `SKILL.md` unchanged at `~/.codex/skills/tadoru/SKILL.md` and prints the MCP registration command to run:

```bash
codex mcp add tadoru -- tadoru mcp
```

or in Codex's `config.toml`:

```toml config.toml
[mcp_servers.tadoru]
command = "tadoru"
args = ["mcp"]
```

Codex skills and MCP registration are user-global, so setup always targets `~/.codex/` regardless of `--scope`.

**opencode**

```bash
tadoru setup --agent opencode
```

This command does not modify any files. It prints the MCP JSON below and an `AGENTS.md` snippet derived from the canonical `SKILL.md` body. Add the JSON to `opencode.json`, then paste the instruction snippet wherever you prefer in `AGENTS.md`. The behavior is the same with or without `--print`.

```json opencode.json
{
  "mcp": {
    "tadoru": { "type": "local", "command": ["tadoru", "mcp"] }
  }
}
```

**Hermes**

```bash
tadoru setup --agent hermes
```

Hermes has first-class skills and MCP, both user-global under `~/.hermes/`. Setup installs the canonical `SKILL.md` unchanged at `~/.hermes/skills/tadoru/SKILL.md` and prints the MCP registration command to run:

```bash
hermes mcp add tadoru --command tadoru --args mcp
```

or in `~/.hermes/config.yaml`:

```yaml config.yaml
mcp_servers:
  tadoru:
    command: "tadoru"
    args: ["mcp"]
```

Because Hermes configuration is user-global, `--scope project` does not apply here — setup always targets `~/.hermes/`.

**Claude Desktop**

```bash
tadoru setup --agent claude-desktop
```

Claude Desktop has no shell, so MCP is the only surface. The command registers the server in `claude_desktop_config.json`:

```json claude_desktop_config.json
{
  "mcpServers": {
    "tadoru": {
      "command": "tadoru",
      "args": ["mcp"]
    }
  }
}
```

**pi**

```bash
tadoru setup --agent pi
```

pi deliberately ships without MCP and does not support native skills. This command does not modify any files: it derives an instruction snippet from the canonical `SKILL.md` body and prints it to stdout. Paste the snippet wherever you prefer in a README or another instruction file that pi reads. The behavior is the same with or without `--print`; `tadoru mcp` is not used.

Other MCP-capable agents not listed above: register `tadoru mcp` as a stdio server using the client's standard MCP configuration — the JSON shape is the same as the Claude Desktop snippet.

## Verify it works

1. Make sure recording is on: `tadoru status` (agents can check this themselves via `get_status`).
2. Ask your agent something like *"check what I was working on in the last hour."*
3. The agent should call `get_timeline` (MCP) or `tadoru timeline` (CLI) and answer from your actual activity.

If the agent reports that recording is off, run `tadoru start` — and if that complains about permissions, `tadoru doctor --fix` (see the [permissions guide](/guides/permissions)).