Troubleshooting

Most setup problems are local runtime or agent-installation issues. ClaudeKit surfaces them before it attempts to launch a process.

Start with doctor

ck doctor
ck doctor --json

ClaudeKit requires Node.js 24 or later and usable local storage. Git is optional, but repository-aware workflows are more useful in a Git project.

Agent not detected

Install and authenticate the agent using its own official instructions, then run ck agents or ck doctor again. ClaudeKit does not install third-party agents or receive their credentials.

Handoff opens manually

If a target does not have a supported documented first-prompt flow, ClaudeKit writes the Markdown handoff locally and tells you where to paste it. Use ck switch <agent> --print to inspect it without launching a target.

Analysis needs review

Impact and unused-file results are static-analysis aids. Treat them as a review list, especially in frameworks that use file-based routing, generated modules, dynamic imports, or runtime discovery.

Terminal output

ck --no-color status
ck --no-animations context "Review the payment flow"
NO_COLOR=1 ck guide

JSON output is always plain. Use the flags above when your terminal, CI environment, log parser, or accessibility preference needs less decoration.