Skip to main content
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 and sign in. 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.
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.

​
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.
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.
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.

​
mutagent hooks import

Send session transcripts that are already on disk (.jsonl files) to Mutagent as traces.
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*.

​
mutagent hooks claude-code

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