CLI commands

Installing the package puts a single callable binary on your PATH: context-mode. Its terminal subcommands are doctor, upgrade, insight, index, search, hook, and statusline. This page covers each of them, plus the slash commands and chat triggers that surface the rest inside your agent.

Diagnostics and maintenance

context-mode doctor

Diagnose your installation. The doctor checks language runtimes, the FTS5 knowledge base, and hook registration for every connected host, then prints a checklist of what passed and what needs attention.

context-mode doctor

Run this first whenever an agent stops routing output or the knowledge base looks empty. The same check is available as the ctx_doctor tool.

context-mode upgrade

Pull the latest context-mode, build it, and reconfigure host hooks in one step. Use this after a new release to keep the server, the dispatcher, and your hook configs in sync.

context-mode upgrade

The equivalent tool is ctx_upgrade.

Session status

context-mode insight

Open the Insight dashboard in your browser. Insight is the hosted analytics layer at https://context-mode.com/insight; the command prints the URL and opens it in your default browser. It takes no arguments.

context-mode insight

See ctx_insight for the underlying tool.

context-mode statusline

Print the Claude Code status line. Claude Code calls this internally to render the context-mode segment of its status bar; it reads a status-line event on stdin and writes the formatted line to stdout. You rarely run it by hand.

context-mode statusline

stats and purge — chat and slash commands

stats and purge have no terminal subcommand. Reach them by typing ctx stats or ctx purge to your agent, or with the /context-mode:ctx-stats and /context-mode:ctx-purge slash commands in Claude Code and Cursor.

ctx stats shows how much context window you saved this session, with a per-tool breakdown of tokens consumed versus tokens avoided. It is read-only — it reports and never resets. context-mode routinely keeps about 98% of a payload's bytes out of context, and this is where you see that number for your own session. The matching tool is ctx_stats.

ctx purge irreversibly wipes the knowledge base and resets session stats: everything you have indexed is deleted and your savings counters return to zero.

Knowledge base from the terminal

You do not need an agent in the loop to populate or query the knowledge base. The index and search commands operate on it directly.

context-mode index

Index a file or directory into the FTS5 knowledge base. Tag the content with a descriptive --source label so you can scope later searches to it.

context-mode index ./src --source codebase

The matching tool is ctx_index.

context-mode search

Search the knowledge base with BM25 ranking and get back focused snippets instead of whole files. Narrow the results with --source when you know which label holds the answer.

context-mode search "retry backoff" --source codebase

The matching tool is ctx_search.

The hook dispatcher

Hosts call context-mode hook <platform> <event> internally to route data-heavy output into the sandbox. You rarely run it by hand, but it is useful for testing: pipe a JSON event into it and inspect what comes back.

echo '{"tool":"Bash","command":"cat large.log"}' | context-mode hook claude-code pretooluse

The dispatcher reads a JSON event on stdin and writes a JSON decision on stdout — the same contract every supported host uses.

Slash commands

In Claude Code and Cursor, every status command is also available as a slash command. They do exactly what their CLI or chat-trigger counterparts do, without leaving the chat.

Related