Tool selection
A simple hierarchy for choosing the right ctx_* tool, and when plain Bash or Read still wins.
Most tasks map to one of four moves: remember, gather, follow-up, or process. Walk the hierarchy in order and pick the first move that fits. Following it keeps raw bytes out of context, which is what frees roughly 95-99% of the window for the work that matters.
The hierarchy
Step 0 — Memory
On a resume or after a compaction, recall before you ask. Run ctx_search with
sort set to timeline to pull back prior decisions, errors, and plans in the
order they happened. The session history is persistent and searchable, so the
context you lost to compaction is still there.
ctx_search({
queries: ["what were we working on", "open decisions", "last error"],
sort: "timeline",
})Search first. Do not ask the user to repeat themselves until search returns nothing.
Step 1 — Gather
When you need to collect a lot of state at once, reach for ctx_batch_execute.
It runs every command, auto-indexes the combined output into the knowledge base,
and returns the matching passages — all in one round trip. One call replaces
thirty, and the raw output never lands in context.
ctx_batch_execute({
commands: [
{ label: "git log", command: "git log --oneline -50" },
{ label: "status", command: "git status --porcelain" },
{ label: "deps", command: "npm ls --all" },
],
queries: ["recent commits touching auth", "uncommitted changes"],
})Step 2 — Follow-up
Already indexed the data and have more questions? Use ctx_search and batch
every question into the queries array so they resolve in a single call instead
of one search per question.
ctx_search({
queries: [
"which files changed in the last release",
"who touched the migration script",
"any TODO comments in the parser",
],
})Step 3 — Process
To filter, count, aggregate, parse, or transform data, write a program with
ctx_execute (or ctx_execute_file to pull a file into the sandbox first). The
program does the work; only what you console.log enters context. This is Think
in Code: program the analysis, do not read the data to compute it by hand.
ctx_execute({
language: "javascript",
code: `
const data = JSON.parse(require('fs').readFileSync('coverage.json', 'utf8'));
const low = Object.entries(data)
.filter(([, v]) => v.pct < 80)
.map(([file]) => file);
console.log(low.length + " files below 80%:", low.slice(0, 5).join(", "));
`,
})When not to use a ctx_* tool
The hierarchy is for getting data into a usable form without flooding context. Two everyday jobs sit outside it.
Plain Bash is right for a short, fixed observation or for mutating state — for
example git, mkdir, and mv. If the output is a handful of lines, or the
command's whole purpose is to change the world rather than produce data to
analyze, just run it.
Plain Read is right when you intend to edit a file. The editor needs the exact
bytes, including whitespace and line numbers, so reading to analyze and reading
to edit are different jobs. Read to edit; reach for ctx_execute_file to
analyze, summarize, or explore.
Pick a tool
ctx_search
Recall and follow-up: query the knowledge base, optionally sorted by timeline.
ctx_batch_execute
Gather: run commands, auto-index, and search in one round trip.
ctx_execute
Process: run code in the sandbox and print only the answer.
ctx_execute_file
Process: pull a file into the sandbox to analyze without reading it into context.