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)
- Codex (npm install -g @openai/codex)
- OpenCode (curl -fsSL https://opencode.ai/install | sh)
- Cursor

Install

Run the guided setup:

npx @idosal/agentcraft

This will:

Auto-detect any installed agent CLIs (Claude Code, Codex, OpenCode, Cursor)
Wire each detected agent into AgentCraft using repo-local provider files while preserving existing entries
Start the server on port 2468
Open the browser UI automatically

Force Reinstall

npx @idosal/agentcraft install --force

Run in Background (Daemon Mode)

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

Custom Port

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

Show All Projects

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

npx @idosal/agentcraft start --all-projects

Launch from a Parent Directory

To manage several Git repositories from one AgentCraft instance, launch from their parent folder:

cd ~/projects
npx @idosal/agentcraft

AgentCraft discovers nested repositories up to three levels deep. Open Spawn Options > Working Directory to select a repository or one of its worktrees before spawning a hero. Agents remain scoped to that selected Git repository.

First Launch

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.

Spawning Heroes

Use the Town Hall command grid:

Key	Action
Q	Open Spawn Options for provider, repository/worktree, template, and isolation choices
W	Quick-spawn with the remembered provider
E	View active sessions
F	Toggle integrated terminal

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

Verify Installation

Run diagnostics:

npx @idosal/agentcraft doctor

This checks provider CLIs and authentication, repo-local integrations, Node and native prerequisites, server and port health, configuration integrity, and Codex sandbox support.