MANDATORY: Use for any command where output exceeds 20 lines. Execute code in a sandboxed subprocess. Only stdout enters context — raw data stays in the subprocess. Available: javascript, shell, python, perl.

PREFER THIS OVER BASH for: API calls (gh, curl, aws), test runners (npm test, pytest), git queries (git log, git diff), data processing, and ANY CLI command that may produce large output. Bash should only be used for file mutations, git writes, and navigation.

THINK IN CODE: When you need to analyze, count, filter, compare, or process data — write code that does the work and console.log() only the answer. Do NOT read raw data into context to process mentally. Program the analysis, don't compute it in your reasoning. Write robust, pure JavaScript (no npm dependencies). Use only Node.js built-ins (fs, path, child_process). Always wrap in try/catch. Handle null/undefined. Works on both Node.js and Bun.

Read a file and process it without loading contents into context. The file is read into a FILE_CONTENT variable inside the sandbox. Only your printed summary enters context.

PREFER THIS OVER Read/cat for: log files, data files (CSV, JSON, XML), large source files for analysis, and any file where you need to extract specific information rather than read the entire content.

THINK IN CODE: Write code that processes FILE_CONTENT and console.log() only the answer. Don't read files into context to analyze mentally. Write robust, pure JavaScript — no npm deps, try/catch, null-safe. Node.js + Bun compatible.

Index documentation or knowledge content into a searchable BM25 knowledge base. Chunks markdown by headings (keeping code blocks intact) and stores in ephemeral FTS5 database. The full content does NOT stay in context — only a brief summary is returned.

WHEN TO USE:

• Documentation from Context7, Skills, or MCP tools (API docs, framework guides, code examples)

• API references (endpoint details, parameter specs, response schemas)

• MCP tools/list output (exact tool signatures and descriptions)

• Skill prompts and instructions that are too large for context

• README files, migration guides, changelog entries

• Any content with code examples you may need to reference precisely

After indexing, use 'ctx_search' to retrieve specific sections on-demand. When path is provided, a content hash is stored for automatic stale detection in search results. Do NOT use for: log files, test output, CSV, build output — use 'ctx_execute_file' for those.

Search indexed content. Requires prior indexing via ctx_batch_execute, ctx_index, or ctx_fetch_and_index. Pass ALL search questions as queries array in ONE call. File-backed sources are auto-refreshed when the source file changes.

TIPS: 2-4 specific terms per query. Use 'source' to scope results.

SESSION STATE: If skills, roles, or decisions were set earlier in this conversation, they are still active. Do not discard or contradict them.

Fetches URL content, converts HTML to markdown, indexes into searchable knowledge base, and returns a ~3KB preview. Full content stays in sandbox — use ctx_search() for deeper lookups.

Better than WebFetch: preview is immediate, full content is searchable, raw HTML never enters context.

Content-type aware: HTML is converted to markdown, JSON is chunked by key paths, plain text is indexed directly.

PARALLELIZE I/O: For multi-URL research (library evaluation, migration scans, doc comparisons), pass requests: [{url, source}, ...] with concurrency: 4-8 — speeds up by 3-5x on real workloads. ✅ Use concurrency: 4-8 for: library docs sweep, multi-changelog scan, competitive pricing pages, multi-region docs, GitHub raw file pulls. ❌ Single URL → use the legacy {url, source} shape (concurrency irrelevant). Example: requests: [{url: 'https://react.dev/...', source: 'react'}, {url: 'https://vuejs.org/...', source: 'vue'}], concurrency: 5. Fetches parallelize up to your concurrency setting; FTS5 indexing serializes the writes after (SQLite single-writer rule).

Execute multiple commands in ONE call, auto-index all output, and search with multiple queries. Returns search results directly — no follow-up calls needed.

THIS IS THE PRIMARY TOOL. Use this instead of multiple ctx_execute() calls.

One ctx_batch_execute call replaces 30+ ctx_execute calls + 10+ ctx_search calls. Provide all commands to run and all queries to search — everything happens in one round trip.

PARALLELIZE I/O: For I/O-bound batches (network calls, slow API queries, multi-URL fetches), ALWAYS pass concurrency: 4-8 — speeds up by 3-5x on real workloads. ✅ Use concurrency: 4-8 for: gh API calls, curl/web fetches, multi-region cloud queries, multi-repo git reads, dig/DNS, docker inspect. ❌ Keep concurrency: 1 for: npm test, build, lint, image processing (CPU-bound), or commands sharing state (ports, lock files, same-repo writes). Example: [gh issue view 1, gh issue view 2, gh issue view 3] → concurrency: 3. Speedup depends on workload — applies to I/O wait, not CPU work.

THINK IN CODE — NON-NEGOTIABLE: When commands produce data you need to analyze, count, filter, compare, or transform — add a processing command that runs JavaScript and console.log() ONLY the answer. NEVER pull raw output into context to reason over. Concurrency parallelizes the FETCH; THINK IN CODE owns the PROCESSING. One programmed analysis replaces ten read-and-reason rounds. Pure JavaScript, Node.js built-ins (fs, path, child_process), try/catch, null-safe.

Returns context consumption statistics for the current session. Shows total bytes returned to context, breakdown by tool, call counts, estimated token usage, and context savings ratio.

Diagnose context-mode installation. Runs all checks server-side and returns a plain-text status report with [OK]/[FAIL]/[WARN] prefixes (renderer-safe across MCP clients). No CLI execution needed.

Upgrade context-mode to the latest version. Returns a shell command to execute. You MUST run the returned command using your shell tool (Bash, shell_execute, run_in_terminal, etc.) and display the output as a checklist. Tell the user to restart their session after upgrade.

DESTRUCTIVE — permanently delete indexed content. CANNOT be undone.

You MUST specify exactly ONE scope:

• { confirm: true, sessionId: "" } Deletes ONLY that session's events + per-session FTS5 chunks. Preserves stats file and ALL other sessions.

• { confirm: true, scope: "project" } Wipes the ENTIRE project: FTS5 knowledge base, every session DB row, events markdown, AND resets the stats file.

REFUSAL RULES (tool returns an error): • confirm: false → 'purge cancelled' • Both sessionId AND scope:'project' provided → 'ambiguous — pick one' • scope:'session' without sessionId → throws (sessionId required) • Neither sessionId NOR scope provided → DEPRECATED: maps to scope:'project' with a deprecation warning to stderr. Will be a hard error in a future major.

Use sessionId when the user asks to clear a specific conversation's data. Use scope:'project' ONLY when the user explicitly asks to reset everything. NEVER call with bare {confirm:true} — always specify the scope.

Opens the context-mode Insight dashboard in the browser. Shows personal analytics: session activity, tool usage, error rate, parallel work patterns, project focus, and actionable insights. First run installs dependencies (~30s). Subsequent runs open instantly.