Claude Code

Claude Code is the primary host for context-mode and exposes its full JSON-hook surface plus the complete set of slash commands. Each event dispatches through context-mode hook claude-code <event>, with the event token lowercased (e.g. context-mode hook claude-code pretooluse). Together those hooks rewrite tool arguments, route data-heavy output into the sandbox, preserve context across compaction, and keep the bulk of raw payload bytes out of your window.

The full hook surface:

• PreToolUse
• PostToolUse
• PreCompact
• SessionStart
• UserPromptSubmit
• Stop

PreToolUse matches a fixed tool set — Bash, WebFetch, Read, Grep, Agent, and the three ctx_ sandbox tools — plus an mcp__ catch-all that fires on every external MCP tool.

Install

/plugin marketplace add mksglu/context-mode

/plugin install context-mode@context-mode

Configure

Configuration is optional. Permission rules live in your Claude settings.json and are written as Tool(match) rules:

• match accepts * wildcards.
• Deny always wins over allow.
• context-mode enforces the same rules inside the sandbox, so a command blocked at the host is also blocked when an agent runs it through ctx_execute.

{
  "permissions": {
    "deny": ["Bash(curl *)", "Bash(rm -rf *)"],
    "allow": ["Bash(git *)", "Bash(npm *)"]
  }
}

By default context-mode stores its knowledge base and session stats under your Claude home directory. To relocate that storage — for a shared machine or per-project isolation — set one or both of these to an absolute path:

See /docs/configuration for the full list of variables.

export CONTEXT_MODE_DIR=/Users/you/.context-mode

Status line (optional)

Claude Code's plugin manifest cannot declare a status line, so this is a one-time manual edit to ~/.claude/settings.json. After saving, restart Claude Code and the bar shows live savings as they accumulate.

{
  "statusLine": {
    "type": "command",
    "command": "context-mode statusline"
  }
}

The bar reads $ saved this session · $ saved across sessions · % efficient. The wiring is path-free — context-mode statusline resolves through the bundled CLI regardless of where the plugin cache lives.

Verify

Confirm the install with the doctor. Run it from the chat — the server-side tool is always available in a plugin install:

/context-mode:ctx-doctor

It checks the following, then reports anything that needs attention:

• Language runtimes
• Performance (Bun vs. normal)
• The three storage paths (sessions, content, stats)
• A server executor self-test
• The FTS5 / SQLite knowledge base
• The PreToolUse and SessionStart hook registration
• The installed version

You can run the same check from a terminal with the CLI, which requires the bundled context-mode binary to be on your PATH:

context-mode doctor

A clean run means context-mode is ready to route your next data-heavy command.

Slash commands

Every status command is available inside the chat, so you can check savings or run the doctor without leaving Claude Code:

• /context-mode:ctx-stats
• /context-mode:ctx-doctor
• /context-mode:ctx-upgrade
• /context-mode:ctx-purge
• /context-mode:ctx-index
• /context-mode:ctx-search
• /context-mode:ctx-insight

Verify your savings

Confirm context-mode is actually saving you tokens, not just installed.

• In the chat, type ctx stats (or run /context-mode:ctx-stats) to see tokens saved, the savings ratio, and a per-tool breakdown for the session.
• Run /context-mode:ctx-doctor (or context-mode doctor from a terminal) to confirm the runtimes, storage paths, FTS5 knowledge base, and the PreToolUse and SessionStart hook registration all pass.
• If you wired the optional status line, the bar shows live savings — $ saved this session · $ saved across sessions · % efficient — so you can watch the numbers climb without leaving the session.

Related