Troubleshooting

Diagnostics

Run the built-in diagnostic tool:

npx @idosal/agentcraft doctor

This checks:

• Provider CLI and install detection
• Whether the selected Node runtime is compatible
• Whether repo-local hooks/plugins are installed without duplicate legacy entries
• Whether the server is running
• Native terminal and Codex sandbox prerequisites
• Configuration, authentication, and port/network health

Common Issues

Hooks not installed / heroes not appearing

npx @idosal/agentcraft install --force

This reinstalls hooks. If external Claude Code sessions still don't appear, verify hooks are present:

npx @idosal/agentcraft doctor

Port 2468 already in use

npx @idosal/agentcraft stop
# Or use a different port:
npx @idosal/agentcraft start --port 3002

Inspect the retained startup output if the process exits or the browser never connects:

npx @idosal/agentcraft logs --lines 300
npx @idosal/agentcraft logs --follow

For a custom port, pass the same port to logs --port.

Integrated terminal fails on Linux

Install the native build prerequisites on Debian or Ubuntu, then rerun your AgentCraft install method:

sudo apt install -y build-essential python3-dev
npx @idosal/agentcraft@latest doctor

For a source checkout or package directory, rebuild node-pty there with npm rebuild node-pty. AgentCraft reports missing privileged OS packages but does not install them automatically.

Internal heroes spawn but never become active

Check that the provider selected in Spawn Options is installed and authenticated in your terminal. For example:

claude --version
codex --version
opencode --version

Run npx @idosal/agentcraft doctor for provider-specific authentication and integration checks, then restart AgentCraft if you installed the provider after the server started.

Agent Teams members not visible

Ensure tmux is installed for full teammate visibility. Without tmux, teammates run in-process and have limited status tracking. Also verify team configs exist at ~/.claude/teams/.

OpenCode heroes not spawning

Verify OpenCode is installed and in your PATH. AgentCraft detects the binary at startup — if you installed OpenCode after starting the server, restart the server.

Cursor option grayed out

The Cursor CLI must be detected at startup. Verify Cursor is installed and the cursor command is available in your terminal.

Codex heroes not spawning

Verify the codex CLI is installed and available in your terminal. If you installed Codex after starting the server, re-run npx @idosal/agentcraft install and restart the server.

On Linux, install Bubblewrap for Codex write sandboxing:

sudo apt install -y bubblewrap

Internal Codex heroes use ~/.agentcraft/codex-home; this is intentional and keeps their resumable threads out of the Codex desktop app's normal task list.

Restore an Uninstall

Every completed uninstall writes a backup manifest before changing managed files. Restore the newest session with:

npx @idosal/agentcraft restore

List or select older sessions when needed:

npx @idosal/agentcraft restore --list
npx @idosal/agentcraft restore --from <path>

This replays the full uninstall backup, including provider config and removed AgentCraft-managed directories. To reinstall integrations without uninstalling first, use npx @idosal/agentcraft install --force instead.

Getting Help

• Discord — Get help and share feedback

• Twitter / X — Follow for updates