ctx_doctor

ctx_doctor is a diagnostic checklist for your context-mode install. It walks the parts that have to be working for the plugin to do its job and reports each one as a pass or a failure, so you can see at a glance what is wrong instead of guessing.

Run it first whenever something is off. A failing check usually points straight at the fix, which saves you from reading logs or re-installing blind.

When called as the ctx_doctor MCP tool, every check runs server-side and the tool returns a plain-text report with [OK], [WARN], and [FAIL] prefixes — no separate command has to run in your shell.

What it checks

• The detectable language runtimes context-mode can execute code with, reported as a count out of 11 (for example Runtimes: 7/11), so you know which languages are available in the sandbox.
• Performance: whether Bun is present for the faster execution path, or a warning to install it for a speed boost.
• The storage directories for sessions, indexed content, and stats, with the resolved path for each.
• A sandbox round-trip: it runs a small program end to end to confirm execution works, not just that a runtime is installed.
• The FTS5 search engine and the native SQLite module that backs the knowledge base, so search and indexing are known to function.
• Hook configuration and hook-script presence for your agent CLI, so context-mode is actually wired into the host and routing fires.
• The installed version, so you can tell whether you are on the latest build.

When to use it

Reach for ctx_doctor at the first sign of trouble: a tool that does not run, a search that returns nothing it should, code that fails to execute in a language you expected, or a host where routing is not firing. The checklist isolates the failing layer before you change anything.

Example

Run the full checklist from the terminal with the context-mode binary.

context-mode doctor

You can also trigger it from chat by typing ctx doctor to your agent, or with the slash command /context-mode:ctx-doctor in Claude Code and Cursor. All three run the same checks.

Related