Troubleshooting.

Start with the layer that failed. Preserve the session, run ID, and existing output before resetting anything or repeating paid work. This guide covers CLI 0.9.0; installed binaries and the connected backend can have different versions.

#Collect a small diagnostic snapshot

In your terminal, kaitoi --version identifies the installed CLI. Inside Code:

/status
/doctor
/config

These show the model, mode, workspace, environment, login state, configuration, and relevant feature diagnostics. /doctor may probe configured local-model endpoints; it is not guaranteed to be an offline operation. Read its specific failure rather than assuming every red line has the same cause.

For model/auth problems, inspect /status and /providers and preserve the chosen environment. For local access, inspect /workspace and /permissions and preserve the files. For extensions, inspect /mcp, /skills, or /hooks and preserve the winning configuration. For delegated work, inspect /agents or /run status and preserve agent/run IDs and evidence. Diagnostics narrow the cause; they do not reset or re-run the work automatically.

Four fictional faults make the checks concrete: intended account A versus active account B; intended bookshop folder versus opened portfolio folder; a configured tool whose process failed to launch; and retained run R1 evidence while a different R2 is selected. None of these checks proves unrelated layers healthy.

#Match the symptom to a first check

Symptom	First check and next distinction
kaitoi missing or wrong version	Check the installed executable path and the installation guide. A source branch is not proof that its release binary is published.
Hosted model refuses access	Check the intended environment and /login; kaitoi connect whoami reports stored CLI account state. External Claude/Codex engines have their own sign-in.
Local model missing	Inspect /providers, the actual endpoint address, server readiness, tool support, and context window. Direct local inference does not require a Connect tunnel.
Tool unavailable	Check mode, workspace trust, feature eligibility, and command enablement before granting anything broader. Deferred schema loading is different from a missing feature.
File refused	Check the current workspace and protected/secret/ignored-file policy. If an edit is stale, reread and prepare a new proposal.
Command refused or failed	Distinguish permission, sandbox availability, missing executable, timeout, and a genuine nonzero check result.
Server still running after commands were disabled	Inspect /processes and stop the owned process by ID. Disabling future command tools does not stop existing ordinary processes.
MCP server/tool missing	Inspect selected scope, launch approval, OAuth if used, /mcp tools <name>, and the tool grant; reload after correcting configuration.
Skill or command missing	Check workspace trust, path, front matter, name, and shadowing using /skills and /help.
Hook does not block	Check event semantics, matcher, exact configuration approval, exit code, and timeout. PostToolUse cannot undo the action.
Background agent disappeared	Inspect /agents; ordinary agents belong to the session, while durable Crew runs have their own lifetime.
Crew held or stopped	Read /run status, /run result, and /run evidence for that run. Follow its recovery guidance instead of creating a duplicate by default.
Local file missing after media generation	Preserve run/file IDs and recover the existing output. A new generation can create a new charge.

#Recover the right state

For conversations, use /sessions and /resume. For eligible file recovery, use undo and rewind and inspect skipped files. For Crew, inspect checkout mirroring and the candidate before switching branches or discarding changes. An empty folder may be eligible for Crew initialization; an existing ordinary non-Git project is not an invitation to initialize over its contents merely to bypass a refusal.

Revoking one session permission does not remove every saved MCP grant, hook approval, or external account permission. Use the control belonging to the failing layer. Avoid deleting settings or evidence stores as a generic repair.

#Share useful evidence

Include the CLI version, operating system, relevant backend environment, short error, action attempted, sanitized IDs, and what succeeded before the failure. Distinguish “accepted,” “completed,” “saved,” and “verified.” Review exported traces before sharing; omit tokens, secrets, signed URLs, and unrelated project content. A reproducible bounded example is more useful than an entire unfiltered session log.