> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# mutagent init, skills, hooks

> Connect a project to Mutagent, install the CLI skill for coding agents, and send Claude Code session telemetry as traces.

These commands connect a project and its coding agent to Mutagent: a project config file, a skill that
teaches coding agents to use the CLI, and hooks that send Claude Code sessions to Mutagent as traces.

**Before you start:** [install the CLI](/cli/installation) and [sign in](/cli/commands/login). A
coding agent signs in with `MUTAGENT_API_KEY=<key> mutagent login --json`, or runs
`mutagent login --browser --json` and shows the printed URL to the person. Run these commands from
the project's root folder. `mutagent skills install` and `mutagent hooks install` only write local
files and work without a sign-in. `mutagent init` and sending traces need one.

## mutagent init

Set up the current project. Writes `.mutagentrc.json` with the endpoint and your selected workspace,
unless the file already exists, and installs the Mutagent CLI skill. It never prompts.

```bash theme={null}
mutagent init --json
mutagent workspaces list --json
```

Success: exit code `0` and `"success": true`, with `configFile` (`.mutagentrc.json`), `config`
(the endpoint and `defaultWorkspace`), and `skillPath` (`.claude/skills/mutagent-cli/`). If `config`
has no `defaultWorkspace`, no workspace is selected yet: run `mutagent workspaces use <workspace-name>`.
Then check the workspace with `mutagent workspaces list --json`.

| Exit code | Meaning and fix |
| - | - |
| `3` | Not signed in (`AUTH_REQUIRED`). [Sign in](/cli/commands/login), then run `mutagent init` again. |
| `2` | The saved key expired or is invalid. Sign in again. |

## mutagent skills install

Install the Mutagent CLI skill for Claude Code, at `.claude/skills/mutagent-cli/SKILL.md`. It teaches
coding agents how to use the CLI.

```bash theme={null}
mutagent skills install --json
```

Success: exit code `0` and `"installed": true`, with `skillDir` and the `files` written. Restart the
coding agent so it loads the skill. No sign-in is needed.

## mutagent hooks install

Add the Mutagent telemetry hooks to `.claude/settings.local.json` for all 11 Claude Code events, so
Claude Code sends session activity to Mutagent as traces. The file is created if missing. Existing
hooks are kept, and running the command again adds nothing twice. The hooks send traces only when the
machine is signed in.

```bash theme={null}
mutagent hooks install --json
```

Success: exit code `0` and `"success": true`, with `settingsPath`, `added` (hooks written now) and
`alreadyPresent`. If `.claude/settings.local.json` is not valid JSON, the command fails with
`SETTINGS_PARSE_ERROR`, backs the file up and leaves it unchanged. Fix the JSON, then run it again.

| Flag | What it does |
| - | - |
| `--cwd <dir>` | Install into this directory instead of the current one. |

## mutagent hooks import

Send session transcripts that are already on disk (`.jsonl` files) to Mutagent as traces.

```bash theme={null}
mutagent hooks import <transcript.jsonl> --dry-run --json
mutagent hooks import <transcript.jsonl> --json
```

Run `--dry-run` first: it reports span counts and unreadable lines and sends nothing. Success is exit
code `0` with `imported` (sessions sent; `0` on a dry run), `dryRun`, and a `sessions` entry per file.
If no file holds a session, the command fails with `NOTHING_TO_IMPORT`. Sending needs a sign-in.
Helix keeps its transcripts in `~/.mutagent/sessions*`.

| Flag | What it does |
| - | - |
| `--max-spans <n>` | Send at most `n` spans per session. The default is 200. |
| `--dry-run` | Convert and report, but send nothing. |

## mutagent hooks claude-code

The handler Claude Code runs for each hook event. `mutagent hooks install` configures these; you do
not run them yourself.

| Event command | Claude Code event |
| - | - |
| `mutagent hooks claude-code session-start` | SessionStart |
| `mutagent hooks claude-code session-end` | SessionEnd |
| `mutagent hooks claude-code stop` | Stop |
| `mutagent hooks claude-code user-prompt-submit` | UserPromptSubmit |
| `mutagent hooks claude-code pre-tool-use` | PreToolUse |
| `mutagent hooks claude-code post-tool-use` | PostToolUse |
| `mutagent hooks claude-code post-tool-use-failure` | PostToolUseFailure |
| `mutagent hooks claude-code subagent-start` | SubagentStart |
| `mutagent hooks claude-code subagent-stop` | SubagentStop |
| `mutagent hooks claude-code pre-compact` | PreCompact |
| `mutagent hooks claude-code post-compact` | PostCompact |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.