context-mode: Context window optimization for AI coding agents

node --version

# First, ensure you have Claude Code v1.0.33+
claude --version

# Install via marketplace (automatic hooks + MCP tools)
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

# Restart Claude Code or reload plugins
/reload-plugins

/context-mode:ctx-doctor

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

claude mcp add context-mode -- npx -y context-mode

# Install context-mode globally
npm install -g context-mode

# Add MCP server to ~/.gemini/settings.json (existing settings will be merged)
# The config adds mcpServers and hooks sections

# Install globally
npm install -g context-mode

# Create .vscode/mcp.json in project root
{
  "servers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

# Create .github/hooks/context-mode.json for hook configuration

# Option A: Local-folder method (macOS/Linux)
git clone https://github.com/mksglu/context-mode.git
cd context-mode
ln -s "$PWD/context-mode" ~/.cursor/plugins/local/context-mode

# Restart Cursor to activate the plugin

# Add to opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["context-mode"]
}

# Optional: Copy routing rules
cp node_modules/context-mode/configs/opencode/AGENTS.md ./AGENTS.md

// ctx_execute - Run code in sandbox, log only result
ctx_execute("javascript", `
  const files = fs.readdirSync('src').filter(f => f.endsWith('.ts'));
  files.forEach(f => console.log(f + ': ' + fs.readFileSync('src/'+f,'utf8').split('\n').length + ' lines'));
`);

// ctx_fetch_and_index - Fetch URL, index content, return summary
ctx_fetch_and_index("https://example.com/docs");

// ctx_batch_execute - Run multiple commands efficiently
ctx_batch_execute([
  { language: "bash", code: "git log --oneline -10" },
  { language: "javascript", code: "console.log(process.env)" }
]);

// ctx_search - Search indexed content via BM25
ctx_search("how to configure authentication", 5);

// ctx_index - Persist content for later search
ctx_index("React docs", reactDocumentationContent);

// ctx_execute_file - Execute file content
ctx_execute_file("analysis.js", "javascript");

# In AI chat - type these directly:
ctx stats       -> context savings, call counts, session report
ctx doctor      -> diagnose runtimes, hooks, FTS5, versions
ctx upgrade     -> update from GitHub, rebuild, reconfigure hooks
ctx purge       -> permanently delete all indexed content
ctx insight     -> open analytics dashboard (99 metrics, 37 insights)

# In terminal:
context-mode doctor
context-mode upgrade
context-mode insight          # opens browser
context-mode statusline       # live counter while running

Session Guide structure after compaction:
- Last Request
- Tasks (with completion status)
- Plans (approvals/rejections)
- Key Decisions
- Files Modified
- Unresolved Errors
- Constraints & Blockers
- Git Operations
- Project Rules
- MCP Tools Used
- Subagent Tasks
- Skills Used
- Rejected Approaches
- External References
- Environment
- Data References

{
  "permissions": {
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf /*)",
      "Read(.env)",
      "Read(**/.env*)"
    ],
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)"
    ]
  }
}

# For hosted/CI environments (blocks private targets too)
export CTX_FETCH_STRICT=1

| Variable | Default | Purpose |
|---|---|---|
| CONTEXT_MODE_DIR | Adapter-specific (~/.claude/context-mode) | Root for context-mode storage. Must be absolute since v1.0.147. |
| CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY | 10 | Cadence for re-injecting MCP-wrapping guidance (range 1-100). |
| CTX_FETCH_STRICT | 0 | Block loopback + RFC1918 + ULA in addition to always-blocked ranges. |

## Test 1: Git history analysis (62 KB context, raw: 986 KB, 94% saved)

> Research https://github.com/modelcontextprotocol/servers - architecture, tech stack, top contributors, open issues. Then run ctx stats

## Test 2: Access log analysis (155 B context, raw: 45.1 KB, 100% saved)

> Analyze this access log for top endpoints and error rates: [paste 500-line log]

## Test 3: Web scraping (3.2 KB context)

> Fetch the Hacker News front page, extract all posts with titles, scores, and domains. Group by domain. Then run ctx stats.

| Platform | MCP | Hooks | Session | Routing | Install Type |
|---|:--:|:--:|:--:|:--:|:--:|
| Claude Code | ✓ | ✓ (auto) | Full | Auto | Plugin marketplace |
| Gemini CLI | ✓ | ✓ | High | Auto | Manual config |
| VS Code Copilot | ✓ | ✓ | High | Auto | Project config |
| JetBrains Copilot | ✓ | ✓ | High | Auto | Settings UI |
| Cursor | ✓ | ✓ (partial) | Partial | Rules file | Local plugin |
| OpenCode | ✓ | ✓ (plugin) | Full | Auto | TypeScript plugin |
| OpenClaw | ✓ | ✓ (plugin) | High | Auto | Gateway plugin |
| Pi Agent | ✓ | ✓ | High | Auto | Extension |
| Codex CLI | ✓ | ✓ | Partial | Auto | Hook config |
| Kiro | ✓ | ✓ | Partial | Manual | Hook config |
| Zed | ✓ | ✗ | ✗ | Manual | MCP only |
| Antigravity | ✓ | ✗ | ✗ | Manual | MCP only |

# Check all systems
ctx doctor

# Upgrade to latest
ctx upgrade

# View detailed stats
cat ~/.claude/context-mode/sessions/stats.json

# Clear corrupted indexed content
ctx purge

Data stored locally:
- ~/.{platform}/context-mode/sessions/ - session events, stats
- ~/.{platform}/context-mode/content/ - indexed content (FTS5)

License: Elastic License 2.0 (source-available, not MIT)
- Use, fork, modify, distribute freely
- Cannot offer as hosted/managed service
- Cannot remove licensing notices