The nine ctx tools: a reference

Your agent sees nine ctx tools and has to pick one for each job. This page names each tool, the fields it takes, what it sends back and one example call. Pick by the job: run code, index content, search it, pick up a session, or check the install.

Free · Local · Private · Forever

Context Mode Engine is source-available under the Elastic License 2.0. Free to use, for all time. It runs on your machine and keeps your data in ~/.context-mode.

Nine tools, one choice per job

Your agent has its own tools for files, shells and the web. Context Mode Engine adds nine more. You want the agent to pick the right one, and you want to read a call and know what it does.

Pick the tool by the job

• Find one fact in big output: ctx_execute.
• Run several commands and ask questions about all their output: ctx_batch.
• Store docs, a folder or a web page to search later: ctx_index.
• Find stored output again: ctx_search.
• Pick up the thread after compaction: ctx_resume.
• See the bytes kept out of context: ctx_stats.
• Check the install: ctx_doctor.
• Update or remove the plugin: ctx_upgrade.
• Delete stored data: ctx_purge.

Each tool accepts only the fields listed below. A field with ? is optional. The source for every field is the tools reference in the plugin repo.

Thinking in Code: why ctx_execute comes first

Most jobs start with ctx_execute. That is Thinking in Code: the agent writes code that reads the data, and the chat gets the result. Pick a job to compare.

⏺ context-mode - ctx_execute (MCP)(language: "javascript",
code: "const res = await fetch("https://jsonplaceholder.typicode.com/photos");
if (!res.ok) throw new Error("HTTP " + res.status);
const photos = await res.json();
let longest = null;
for (const p of photos) {
  if (!longest || p.title.length > longest.title.length) longest = p;
}
const withEst = photos.filter(p => p.title.includes("est")).length;
const ties = photos.filter(p => p.title.length === longest.title.length).map(p => p.id);
console.log(JSON.stringify({ total: photos.length, longest: { id: longest.id, title: longest.title,…
intent: "longest photo title and count of titles containing \"est\"")
  ⎿  exit 0 · 239 B
     {
       "total": 5000,
       "longest": {
         "id": 653,
         "title": "temporibus commodi et fugit doloremque reprehenderit exercitationem necessitatibus au…
         "length": 86
       },
       "longestTieIds": [
         653
       ],
       "titlesContainingEst": 892
     … +1 lines
     239 B produced, 254 B returned

⏺ context-mode - ctx_execute (MCP)(language: "javascript",
code: "const photos = await (await fetch("https://jsonplaceholder.typicode.com/photos")).json();
const wholeWord = photos.filter(p => /\best\b/.test(p.title)).length;
console.log(JSON.stringify({ wholeWordEst: wholeWord, substringEst: photos.filter(p => p.title.incl…
intent: "count titles with \"est\" as a whole word vs substring")
  ⎿  exit 0 · 40 B
     {"wholeWordEst":597,"substringEst":892}
     40 B produced, 54 B returned

⏺ context-mode - ctx_execute (MCP)(language: "shell",
code: "d=$(mktemp -d) && cd \"$d\" && curl -sSfL -o Linux_2k.log https://raw.githubusercontent.com/…
intent: "authentication failure counts and top rhost values")
  ⎿  exit 0 · 273 B
     lines:     1999
     auth failure lines: 490
     --- failure lines with non-empty rhost, top 3 ---
       80 rhost=150.183.249.110
       23 rhost=n219076184117.netvigator.com
       23 rhost=207.243.167.114
     --- distinct rhosts among failures ---
           48
     --- failure lines with empty rhost ---
     1
     273 B produced, 288 B returned

⏺ context-mode - ctx_execute (MCP)(language: "shell",
code: "cd \"$(ls -td /tmp/tmp.* 2>/dev/null | head -1)\" 2>/dev/null || cd \"$TMPDIR\"; f=$(ls -t *…
  ⎿  exit 0 · 0 B
     0 B produced, 14 B returned

⏺ context-mode - ctx_execute (MCP)(language: "shell",
code: "d=$(mktemp -d) && cd \"$d\" && curl -sSfL -o Linux_2k.log https://raw.githubusercontent.com/…
  ⎿    80 rhost=150.183.249.110
       23 rhost=n219076184117.netvigator.com
       23 rhost=207.243.167.114
       20 rhost=60.30.224.116
       15 rhost=195.129.24.210
       14 rhost=218.188.2.4
     168 B produced, 168 B returned

⏺ context-mode - ctx_execute (MCP)(language: "python",
code: "import subprocess, re, html
out = subprocess.run(["curl","-sL","--max-time","30","https://news.ycombinator.com/"],capture_outpu…
rows = re.findall(r'<tr class="athing[^"]*" id="(\d+)">.*?<span class="titleline"><a href="([^"]+)"…
scores = dict(re.findall(r'<span class="score" id="score_(\d+)"[^>]*>(\d+) points?</span>', out))
for i,(id_,href,title,dom) in enumerate(rows[:10],1):
    print(f"{i}. {html.unescape(re.sub('<[^>]+>','',title))} | points: {scores.get(id_,'?')} | doma…
print("rows found:", len(rows))")
  ⎿  1. Show HN: Wikihack – HackerTube, but for Wikipedia articles mentioned on HN | points: 93 | domain…
     2. Show HN: HackerBooks – HackerTube, but for books mentioned on HN | points: 1305 | domain: hacker…
     3. Postgres 19 is late because so many more bugs are being found now | points: 348 | domain: rhaas.…
     4. F/OSS Comics #13: BSD Unix, Part 3 – The Beginning of BSD Unix | points: 100 | domain: fosscomic…
     5. HackerTube: YouTube built from videos recommended by HN | points: 2512 | domain: karpathy.bearbl…
     6. Ask HN: Which TV do you recommend for privacy? | points: 329 | domain: none (HN internal)
     7. Mystery of 60-Second Fluctuations in Power Grids Solved | points: 103 | domain: fz-juelich.de
     8. Bones may release proteins that slow aging and extend life span | points: 51 | domain: science.o…
     9. Trigger.dev customer environment variables exposed | points: 73 | domain: trigger.dev
     10. Nibnib: Image compression with extreme decompression speed | points: 135 | domain: github.com/r…
     rows found: 28
     1,064 B produced, 1,064 B returned

⏺ context-mode - ctx_batch (MCP)(commands: ["git shortlog -sn -300 HEAD","git log --stat --format='commit %h %an: %s' -300"],
queries: ["fix(server)","release: v8.3"])
  ⎿  ## fix(server)
      docs/guide/troubleshooting.md | 14 ++++++++++++++
      1 file changed, 14 insertions(+)
     commit 6894f5c kingmaker: fix(server): handle file watcher errors without crashing (#23503)
      packages/vite/CHANGELOG.md | 32 ++++++++++++++++++++++++++++++++
      packages/vite/package.json |  2 +-
      2 files changed, 33 insertions(+), 1 deletion(-)
     commit b28db28 owenn: fix(server): match static aliases on path boundaries (#23643)
      packages/vite/CHANGELOG.md | 8 ++++++++
      packages/vite/package.json | 2 +-
      2 files changed, 9 insertions(+), 1 deletion(-)
     commit c3e06f9 翠: fix(server): store ids to `safeModulePaths` rather than URLs (#23656)
     … +174 lines
     318,426 B produced, 11,688 B returned

The tools

ctx_execute

Runs code or a shell command in your project folder. Only what the code prints comes back to the model.

• Inputs: language, code, file?, intent?, timeoutMs?, background?, summary?. The language is shell, powershell, javascript, typescript, python, or the name of any runtime on your PATH.
• Reply: what the code prints, at most 16,384 B. Bigger output gives a preview of at most 4,096 B, the full output goes to the index, and the reply ends with a ctx_search call. With intent, the matching parts come back. With file, the code reads the path from CTX_FILE. The default and maximum timeout is 600,000 ms. With background set to true, the call starts the process and returns its process id.

ctx_execute({language:"shell",code:"git log --oneline -5"})

More on the sandbox page.

ctx_batch

Runs several shell commands, indexes their output, and answers several search queries over it, in one call. The commands run one at a time, in the order you give.

• Inputs: commands[], queries[]. Both are required.
• Reply: the matching parts of the output and a one-line footer.

ctx_batch({commands:["git log --oneline -5"],queries:["recent changes"]})

ctx_index

Stores content in the project index so the agent searches it later and reads it only once. It takes a file, a folder (it follows each .gitignore), a text, or a URL, which it fetches and turns into Markdown.

• Inputs: path?, content?, url?, source?. Give one of path, content or url.
• Reply: the source label and the count of stored chunks. A path label uses forward slashes on every OS, for example nested/notes.md.

ctx_index({path:"docs/api.md"})

ctx_search

Searches what ctx_index stored and earlier sandbox output in this project. Pass several queries in one call.

• Inputs: queries[], scope? (session, worktree or project; the default is worktree), source?, offset?, sort? (relevance or timeline), after?.
• Reply: 5 hits per reply, each with its source. A More: line gives the next page with offset. Set sort to timeline for oldest-first order, paged with after. Set source to decision to search the rows where you answered a question.

ctx_search({queries:["auth middleware"]})

More on the search page.

ctx_resume

Gives the agent its place back after compaction or a resumed session, before it repeats earlier work.

• Inputs: session?, seq?.
• Reply: the state block, at most 2,048 B: the last task and request, changed files, open errors and search terms. A large row shows as a pointer line with a number. Call again with that number as seq to read the full row.

ctx_resume({})

More on the long sessions page.

ctx_stats

Shows how many bytes stayed out of the context, per session, per project and for all time.

• Inputs: an empty object.
• Reply: a Markdown table, per agent. The agent shows it to you as it is.

ctx_stats({})

ctx_doctor

Checks the install from D1 to D11: version, Node and node:sqlite, host config and hooks, MCP, project, database, index, hook timing and the shell. It only reads.

• Inputs: an empty object.
• Reply: a table with one row per check. Each row shows PASS or names the command that fixes it. A report over 4,096 B goes to the index whole, under the source ctx_doctor:report, and the reply points to it with a ctx_search call.

ctx_doctor({})

More on the doctor page.

ctx_upgrade

Updates the plugin for this agent, or removes it. It rewrites only the entries of Context Mode Engine in the host config, and keeps your own entries and settings, for example hook timeouts.

• Inputs: mode? (upgrade or uninstall), confirmDelete?.
• Reply: a table of what changed, and whether the agent needs a restart.

ctx_upgrade({})

ctx_purge

Deletes stored data for good: one session, one indexed source, or everything for this project. It works on this project's context.db only, in one write.

• Inputs: session?, source?, project?. Give exactly one.
• Reply: a short line that names what it deleted.

ctx_purge({source:"old-docs"})

More on the privacy page.

What you get

You read any ctx call in your agent's log and know what it does. Your agent picks the tool that keeps the most output on your machine, and the model reads a short reply.

Prompts to give your agent

Use ctx_execute to count the TODO lines in src and print only the total.

Search the earlier test output with ctx_search for "timeout" and show the top hit.