Claude Code
Primary integration with Anthropic's Claude Code CLI.
Claude Code is AgentCraft's primary integration. AgentCraft works by installing lightweight hooks into Claude Code that report session events to the server.
How It Works
AgentCraft installs event hooks into the current repository's .claude/settings.local.json. Existing user hooks are preserved, and legacy global AgentCraft hook entries are removed to avoid duplicate events. The hooks fire Node scripts that send events (hero spawn, active, idle, file access, etc.) to the local AgentCraft server via HTTP.
Hook Events
| Event | Trigger | Purpose |
|---|---|---|
| SessionStart | New Claude Code session | Spawn a hero on the map |
| UserPromptSubmit | User sends a prompt | Hero becomes active |
| Stop | Session stops | Hero goes idle |
| PreToolUse (Task) | Subagent spawned | Track subagent on map |
| PreToolUse (Read/Write/Edit) | File operations | Track file access |
| PreToolUse (AskUserQuestion) | Agent asks a question | Hero enters "awaiting input" state |
| SubagentStop | Subagent finishes | Update subagent status |
| PermissionRequest | Agent needs approval | Hero glows yellow |
Hero Types
External Heroes
Start a Claude Code session in any terminal while AgentCraft is running:
claudeThe session is automatically detected via hooks and appears on the map. Everything you do in that terminal is reflected in real time.
Internal Heroes
Press Q at the Town Hall to open Spawn Options, then select Claude Code. Afterward, W quick-spawns another hero with the remembered provider. Internal heroes run in the background and you interact with them entirely through the game interface.
Features
Claude Code heroes support all AgentCraft features:
- Real-time conversation via the Side Panel
- Plan review and approval workflow
- Permission request handling (tool use approvals)
- File operation tracking
- Git diff viewing
- Model selection (Opus, Sonnet, Haiku, or custom)
- Fork and handoff to other heroes
- Agent Teams support
- Subagent tracking
Model Selection
Use the model dropdown at the top of the Side Panel to change models per hero:
| Option | Behavior |
|---|---|
| Default | No --model flag (recommended for Bedrock/Vertex) |
| Opus | --model opus |
| Sonnet | --model sonnet |
| Haiku | --model haiku |
| Custom | Any model string (e.g., ollama:llama3) |
The system auto-syncs the displayed model with the one actually being used.