# Install Tracetoon (for agents)

<!-- Generated by scripts/agent-surfaces.ts from src/integrations/registry.ts. Do not edit by hand. -->

Tracetoon is a skill (`SKILL.md` plus a launcher) and a `tracetoon` binary.
It needs `git` and the GitHub CLI (`gh`), signed in. Pick the first route
your host allows.

## 1. npm (after the first npm release)

Needs Node.js 18+ (or Bun). Downloads the prebuilt binary for this machine
from npm, installs its skill into every agent found, and adds the PR hook:

```sh
npx tracetoon@latest setup --json
npx tracetoon@latest doctor --json
```

`setup --agent <id>` limits it to one host; `--no-hook` skips the hook.
The hook runs the binary from where npm put it, and `npx` keeps that in its
cache, so for a lasting `tracetoon` command and hook prefer
`npm install -g tracetoon`, then `tracetoon setup --json`. Before Tracetoon
is on npm, `npx` fails with a 404; use the next route.

## 2. Claude Code plugin

```sh
claude plugin marketplace add Tracetoon/tracetoon
claude plugin install tracetoon@tracetoon
```

Inside a session the same commands are `/plugin marketplace add Tracetoon/tracetoon` and
`/plugin install tracetoon@tracetoon`. The plugin carries the skill and runs
its bundled copy under Bun or Node 22+. The installer (route 5) adds the
prebuilt binary and the PR hook.

## 3. Skills CLI or GitHub CLI (`gh skill`)

Both read the skill from the `release` branch, which carries the built bundle.
`main` and the release tags hold source only, so a plain `Tracetoon/tracetoon`
installs a copy that can't run (the launcher exits 3 and says so).

```sh
npx skills add Tracetoon/tracetoon#release --skill tracetoon -g -y
gh skill install Tracetoon/tracetoon plugin/skills/tracetoon --pin release --scope user
```

With `-y` the skills CLI installs for every agent it detects; `-a <agent>`
picks one. `gh skill` takes `--agent <agent>` (default GitHub Copilot), for
example `claude-code` or `codex`.
The skill runs its bundled copy under Bun or Node 22+. `gh skill` writes
files without the executable bit: on macOS and Linux run
`chmod +x <skill folder>/bin/tracetoon` once. Neither adds the PR hook;
`<skill folder>/bin/tracetoon hook install` does.

## 4. Skill from the release, with `gh`

Uses only `gh`, which Tracetoon needs anyway:

```sh
gh release download --repo Tracetoon/tracetoon --pattern tracetoon-skill.zip --dir "${TMPDIR:-/tmp}/tracetoon" --clobber
unzip -o "${TMPDIR:-/tmp}/tracetoon/tracetoon-skill.zip" -d ~/.agents/skills/
```

```powershell
gh release download --repo Tracetoon/tracetoon --pattern tracetoon-skill.zip --dir "$env:TEMP\tracetoon" --clobber
Expand-Archive "$env:TEMP\tracetoon\tracetoon-skill.zip" "$HOME\.agents\skills" -Force
```

The archive holds a `tracetoon/` folder; extract it into the skills folder
your host reads (table below). On first use the
launcher exits with code 3 when it finds no runtime; with the user's
agreement, rerun with `TRACETOON_ALLOW_DOWNLOAD=1` and it downloads the
release binary through `gh` and checks its SHA-256.

## 5. Installer (installs the binary, every skill copy and the PR hook)

Agent sandboxes usually block piping a download into a shell, so ask the user
to run it, or to approve it:

```sh
curl -fsSL https://raw.githubusercontent.com/Tracetoon/tracetoon/main/install.sh | sh
```

```powershell
irm https://raw.githubusercontent.com/Tracetoon/tracetoon/main/install.ps1 | iex
```

`TRACETOON_NO_HOOK=1` skips the PR hook; `TRACETOON_VERSION=<tag>` pins a release.

## 6. MCP server (hosts without skills or a shell)

With the runtime installed (`npm install -g tracetoon` from route 1, the
installer from route 5, or the plugin), `tracetoon mcp` serves Tracetoon
over MCP on stdio; after the first npm release `npx -y tracetoon@latest mcp`
works without an install. The Claude Code plugin registers it already, and the
Cursor plugin and Gemini extension start it through `npx`. For another
Claude Code setup:

```sh
claude mcp add tracetoon -- tracetoon mcp
```

Any host that reads an `mcpServers` map:

```json
{
  "mcpServers": {
    "tracetoon": { "command": "tracetoon", "args": ["mcp"] }
  }
}
```

Tools: `tracetoon_status` (read-only doctor checks), `tracetoon_prepare_pr`
(evidence brief and drafting guidance; you write `title.txt` and `body.md`
in the run folder) and `tracetoon_publish_pr` (`dryRun` is true unless you
pass false). The skill and its references are resources under
`tracetoon://skill/`. On Windows, if the host can't start `tracetoon`
directly, use `cmd /c tracetoon mcp`.

## Where each host reads the skill

| Host | Personal skill folder | PR hook |
| --- | --- | --- |
| Claude Code | `~/.claude/skills/tracetoon` | yes |
| Codex | `~/.agents/skills/tracetoon` | yes |
| Antigravity | `~/.gemini/config/skills/tracetoon` | yes |
| Factory Droid | `~/.agents/skills/tracetoon` | yes |
| Copilot | `~/.agents/skills/tracetoon` | yes |
| Cursor | `~/.agents/skills/tracetoon` | yes |
| OpenCode | `~/.agents/skills/tracetoon` | yes |
| Kilo CLI | `~/.agents/skills/tracetoon` | yes |
| Kiro | `~/.kiro/skills/tracetoon` | yes |
| Cline | `~/.agents/skills/tracetoon` | yes |
| Junie | `~/.junie/skills/tracetoon` | yes |
| Devin | `~/.agents/skills/tracetoon` | via Claude Code |
| Goose | `~/.agents/skills/tracetoon` | yes |
| Qwen Code | `~/.qwen/skills/tracetoon` | yes |
| Crush | `~/.agents/skills/tracetoon` | yes |
| Amp | `~/.agents/skills/tracetoon` | yes |
| Zed | `~/.agents/skills/tracetoon` | no |
| Warp | `~/.agents/skills/tracetoon` | no |

## Check the install

```sh
tracetoon doctor --json
```

Restart the agent after installing; hosts read skills and hooks at startup.
