Check and repair your setup with doctor

When the hooks seem quiet, run one command: context-mode doctor. It checks every agent on your machine, step by step, from D1 to D11. Each check shows PASS when it is ready, or prints the command that fixes it. context-mode setup then repairs what doctor finds.

Free · Local · Private · Yours to keep

Context Mode Engine is source-available under the Elastic License 2.0. Use it, copy it, change it and share it at zero cost, for as long as you follow the licence terms. It runs on your machine, sends zero usage data, and keeps your data in ~/.context-mode.

The hooks seem quiet

You run your tests and the whole log lands in the chat. Or the agent reads a big page in full. You expected a short reply from the sandbox. Now you want to know which part to look at: Node, the config, the hooks or the database.

Doctor answers that in one run. It checks each part in a fixed order and names the fix for each one.

Step 1: run doctor

Inside your agent, run /ctx-doctor. Your agent can also call the ctx_doctor tool. In Pi, or in any terminal, run:

The terminal command comes with the npm package. Agents that installed with their own command (see Install Context Mode Engine in your agent) get it once with:

To check one agent, add --agents <id>, for example context-mode doctor --agents codex.

Step 2: read the checks, D1 to D11

Doctor runs D1 to D11 in order for each agent (D5b runs right after D5). Each check shows PASS, or names what to fix and the command for it. The checks fall into four groups:

1. Version, Node and shell (D1, D2, D11).
   • D1: your build is older than the newest release. Fix: run ctx_upgrade. D1 uses git ls-remote with a 10 s time cap; offline it reports UNKNOWN and the other checks go on.
   • D2: Node is older than 24.15.0, or node:sqlite fails to load. Fix: install Node 24.15.0 or later.
   • D11: the shell needs a fix (sh on macOS and Linux, Git Bash on Windows). Fix: install Git for Windows.
2. Your agent's config (D3, D4, D5b, D10).
   • D3: the MCP entry, a hook entry or the hook timeout needs a fix. Fix: run ctx_upgrade.
   • D4: older context-mode entries stay in the config. Fix: run ctx_upgrade.
   • D5b: Claude Code hooks and VS Code chat.useClaudeHooks both fire for one repo. Fix: turn off one of the two.
   • D10: the hooks run in a mode that needs a change. Fix: the command named in the row.
3. Hooks, MCP and project folder (D5, D6, D7).
   • D5: a real hook call returns a reply in the wrong shape, or too slowly. Fix: run ctx_upgrade.
   • D6: the MCP handshake between your agent and the server fails. Fix: the command named in the row.
   • D7: the Engine sees a different project folder from the one your agent runs in. Fix: restart the agent in the correct directory.
4. Your local data (D8, D9).
   • D8: the schema or the integrity of context.db needs a fix. Fix: run ctx_upgrade, or doctor heals the file on the next run and keeps the old data as context.db.<ts>.bak.
   • D9: the index sources and chunks need a fix. Fix: the command named in the row.

Source: the check order and texts in constants.ts. Codex asks you to trust its hooks; context-mode setup --agents codex marks them trusted.

Here is a sample report where every check is ready. Run it to see the rows tick in order, the way the real command prints them:

Each other row names the command that fixes it. Run that command, then run doctor again. In a terminal, doctor asks one question for an agent that needs a fix: fix now.

Step 3: repair with setup

context-mode setup is the repair path for every agent. It works in five steps:

1. It finds each agent: its command on your PATH or its config folder.
2. It shows the plan: the exact command or file change for each agent.
3. It asks once, then applies the plan.
4. It checks each agent: the config entry, old entries, an MCP handshake and one hook call.
5. It rolls back an agent whose check needs a fix, and prints a gh issue create command with a report file.

Setup backs up every file it touches under ~/.context-mode/backups. It leaves CLAUDE.md, AGENTS.md and your other instruction files as they are. Run it again at any time: a second run keeps every file as it is.

Setup options

Exit codes

• 0: every check and step passed.
• 1: a check or a step needs a fix.
• 2: a usage error, or setup needs an answer while it runs in a script or CI. Add --yes.
• 130: you pressed Ctrl-C.

Step 4: ask for help with the report

When a row still asks for a fix after you run its command, bring the report. Doctor removes secrets from it before it prints. A row that needs a fix also prints a gh issue create command, and the report file is under ~/.context-mode/reports/.

• Post the full /ctx-doctor report on Discord.
• Or open the bug form and paste the report.

What you get

You see each part of your setup in one list, with PASS or the exact command to run. Setup repairs the rest, backs up what it touches and lets you roll it back. Doctor runs on your machine; its one network call is the D1 version check.

Next, rerun the Engine benchmark on your machine.