Run code in a sandboxed subprocess. Languages: javascript, shell, typescript, python, perl.

Only what you console.log() enters your conversation — the bytes your code processes stay in the sandbox.

WHEN:

• You intend to derive an answer FROM data (filter, count, aggregate, parse, compare) — print only the answer

• Output shape or size cannot be predicted before execution (recursive finds, repo-wide greps, list endpoints, log scans)

• You would read raw output then mentally compute — that compute belongs here, where its inputs stay out

• You need a long-running process kept alive (dev server, watcher, daemon) — pass background: true to detach on timeout

• Output may be large but you want recall-by-topic later — pass intent; outputs over ~5KB are auto-indexed and only section titles + previews come back

WHEN NOT:

• Single short observational command you will consume verbatim (whoami, pwd, git status on a clean tree) — Bash is simpler

• File mutations (Edit/Write) or navigation (cd/ls) — Bash is the right surface

RETURNS: Only what your code prints. Wrap risky calls in try/catch — uncaught errors go to stderr. Drill in via ctx_search(queries: [...]).

EXAMPLE: ctx_execute(language: "javascript", code: "const out = require('child_process').execSync('npm test', {encoding:'utf8', stdio:['ignore','pipe','pipe']}); console.log(out.split('\n').filter(l => /(FAIL|✗|×|Error:|Tests +.*(failed|passed))/i.test(l)).slice(0, 60).join('\n'))")

Read a file into a sandboxed FILE_CONTENT variable and run code over it. Only what you console.log() enters your conversation — the file bytes stay in the sandbox. Same principle as ctx_execute, scoped to one named file.

WHEN:

• You want to KNOW SOMETHING ABOUT a file (line count, matches of a pattern, parsed structure, statistical aggregate) without needing to SEE all of it

• The file is structured (CSV, JSON, log, code) and a code-level derivation is cheaper than reading verbatim

• The file is large enough that reading it would burn conversation memory you need for the actual work

• The derivation may itself be large and you want recall-by-topic later — pass intent; outputs over ~5KB are auto-indexed and only matching sections come back, retrievable via ctx_search

WHEN NOT:

• You intend to EDIT the file — use Read so the subsequent Edit can match the exact text

• You only need one specific line and you know its offset — Read with offset/limit is the simplest path

• The file is small AND you will consume all of it — Read directly

RETURNS: Only what your code prints. FILE_CONTENT holds the raw bytes inside the sandbox; nothing else leaves. Auto-indexed output returns searchable section titles + previews instead of raw stdout.

EXAMPLE: ctx_execute_file(path: "huge.log", language: "javascript", code: "const errs = FILE_CONTENT.split('\n').filter(l => /ERROR|FATAL/.test(l)); console.log(${errs.length} error lines); console.log(errs.slice(-5).join('\n'))")

Store content in a searchable knowledge base (BM25 over FTS5). Splits markdown by headings, keeps code blocks intact, persists the raw chunks. The full content stays in storage — retrieve any section on-demand via ctx_search; nothing is summarized or truncated.

WHEN:

• 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 too large to keep verbatim in conversation

• README files, migration guides, changelog entries

WHEN NOT:

• Log files, test output, CSV, or build output — use ctx_execute_file, which processes in-sandbox without persisting bytes

• Single-use ephemeral content you will not query later — keep it inline if it fits, or ctx_execute_file it

RETURNS: Indexing metadata: chunk counts, source label, and the exact ctx_search call shape. Raw content is NOT echoed back. With path, a content hash lets ctx_search auto-flag staleness later.

EXAMPLE: ctx_index(content: "# React useEffect\n\nThe Effect Hook lets you ...", source: "react-useeffect-docs") EXAMPLE: ctx_index(path: "/path/to/large-spec.md", source: "openapi-v2-spec")

Search the unified knowledge base: content you indexed plus auto-captured session memory (decisions, errors, blockers, plans, user prompts, compaction guides — 26 categories). Stemming, trigram and typo-tolerant matchers rank each query.

WHEN:

• You want to recall something already in storage instead of re-reading raw sources

• You have several related questions about one body of knowledge — batch them into one call

• You want one labelled source (pass source — partial match is fine) or a cross-session view (pass sort: "timeline")

• You want to filter by content shape (contentType: "code" or "prose")

WHEN NOT:

• The data was never indexed and no session memory surrounds it — capture first, then query

• You have one ad-hoc question about unindexed data — run code in the sandbox tool instead

RETURNS: Per-query ranked sections with window-extracted snippets. Use 2-4 technical terms per query. Labels: decision, error, blocker, plan, user-prompt, compaction. Results taper in the rolling time window and block after the hard cap (CONTEXT_MODE_SEARCH_WINDOW_MS).

EXAMPLE: ctx_search(queries: ["root cause", "proposed fix"], source: "issue-#683")

Fetches URL content, converts HTML to markdown (JSON chunked by key paths, plain text indexed directly), persists it in a searchable knowledge base, returns a small preview window per source. Raw page bytes never enter your conversation — they live in storage, retrievable via ctx_search. Every fetch is cached on disk for 24h by default; override per-call with ttl.

WHEN:

• You need web content (docs, changelogs, API references, spec pages) and the raw bytes should NOT enter your conversation

• Multi-URL research (library evaluation, migration scans, doc comparisons): pass the requests array and concurrency 2-8 for parallel I/O

• You want repeat lookups against the same URL to be cheap (cache hits return only a hint, no re-fetch)

• You want a guaranteed-fresh fetch (ttl: 0 or force: true)

WHEN NOT:

• You already have the content locally — store it via the inline index tool

• The page is SPA-rendered (JavaScript-required) — this is a plain HTTP fetch, no headless browser

RETURNS: Per-source preview windows around indexable headings plus indexing metadata (chunk counts, source labels, cache). Raw content is NOT echoed back. concurrency parallelizes the fetch phase only — FTS5 is single-writer, so index writes always serialize. Use 4-8 for I/O-bound batches; lower it under per-IP rate limits.

EXAMPLE: ctx_fetch_and_index( requests: [{url: "https://react.dev/...", source: "react"}, {url: "https://vuejs.org/...", source: "vue"}], concurrency: 5 )

Run multiple commands in ONE call. Every command's output is auto-indexed into the knowledge base; pass queries and the matching sections come back in the same round trip. Concurrency parallelizes the fetch phase only — derivation still belongs in code, so add a processing command that consumes indexed output and prints just the answer.

WHEN:

• You have 3+ related commands you would otherwise run sequentially (multi-issue lookups, git log + diff + blame, multi-file reads, multi-region cloud queries)

• You want to gather AND query in one round trip — pass queries so matching sections come back inline

• You want to parallelize I/O-bound work — pass concurrency 2-8 (network calls, gh CLI, cloud APIs, multi-repo git reads)

• Combined output is large enough that a later ctx_search pass would itself be expensive

WHEN NOT:

• Single command with no follow-up query — run it in the sandbox tool directly

• CPU-bound or stateful commands — keep concurrency at 1 (npm test, build, lint, port-binding servers, lock-file holders, anything racing on the same resource)

RETURNS: Auto-indexed section list per command label, plus top matches per query. Raw output is NOT echoed in full.

EXAMPLE: ctx_batch_execute( commands: [ {label: "issue 1", command: "gh issue view 1"}, {label: "issue 2", command: "gh issue view 2"} ], queries: ["root cause", "proposed fix"], concurrency: 2 )

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.

DESTRUCTIVE: permanently delete indexed content. Cannot be undone. Requires confirm:true and exactly one scope.

WHEN:

• User explicitly asks to clear a specific session ('purge this session', 'wipe this conversation')

• User explicitly asks to reset the whole project ('reset everything', 'wipe the knowledge base')

WHEN NOT:

• User says 'reset', 'clear', or 'wipe' without naming a scope -> ask which scope before calling

• User wants to free memory -> recommend ctx_stats first

SCOPES (pass exactly one):

• Per-session: ctx_purge(confirm: true, sessionId: "") — deletes that session's events and chunks; siblings and stats preserved.

• Per-project: ctx_purge(confirm: true, scope: "project") — wipes the FTS5 knowledge base, every session DB row, events markdown, and resets stats. Preview with ctx_stats first.

CONTRACT:

• confirm:true is required; confirm:false returns 'purge cancelled'.

• sessionId and scope:'project' together return 'ambiguous - pick one'.

• scope:'session' without sessionId throws.

• Bare {confirm:true} is deprecated: maps to scope:'project' with a warning; will hard-error later.

RETURNS: A summary of removed rows + the resolved scope.

EXAMPLE: ctx_purge(confirm: true, sessionId: "7c8a-1234-5678-9abc-def012345678")

Opens the context-mode Insight dashboard (https://context-mode.com/insight) in your default browser — a dashboard launcher for the hosted analytics layer, not a Q&A engine. Insight surfaces per-engineer productive rate, retry waste, blocker detection, and role-narrowed views for CTO, EM, IC, CISO, FinOps, and DevOps. For natural-language queries over your indexed content, use ctx_search.