Installation & Setup

Prerequisites

Node.js 18 or later
At least one supported AI agent CLI installed:
- Claude Code (npm install -g @anthropic-ai/claude-code)
- OpenCode (curl -fsSL https://opencode.ai/install | sh)
- Cursor

Run the guided setup:

npx @idosal/agentcraft

This will:

Auto-detect any installed agent CLIs (Claude Code, OpenCode, Cursor)
Install hooks for each detected agent (merges without touching your existing hooks)
Start the server on port 2468
Open the browser UI automatically

For each detected agent:

Claude Code — hooks installed to ~/.claude/settings.json (backed up to settings.backup.json)
OpenCode — plugin installed to ~/.config/opencode/plugins/agentcraft.js
Cursor — hooks installed to ~/.cursor/hooks.json

npx @idosal/agentcraft install --force

npx @idosal/agentcraft start -d
npx @idosal/agentcraft stop   # Stop later

npx @idosal/agentcraft start --port 3002
# or shorthand:
npx @idosal/agentcraft start -p 3002

By default AgentCraft only shows agents from the current directory. To see sessions from all projects:

npx @idosal/agentcraft start --all-projects

On first launch, an interactive tutorial guides you through the basics:

Welcome — Introduction to the RTS interface
Commands — The command grid at the bottom; spawn your first hero
Hero Spawn — Send your first prompt to the hero
Observe — Activity bubbles and the yellow glow indicating the agent needs input
Status Widget — The agent status panel showing all heroes
Complete — The War Advisor introduces itself for ongoing tips

Steps 2 and 3 wait for you to take action before advancing.

Use the Town Hall command grid:

External sessions (agents started in a separate terminal) are automatically detected and appear on the map.

Run diagnostics:

npx @idosal/agentcraft doctor

This checks: CLI installed, hooks in PATH, hooks present in settings, server running, Node.js version.