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 · Yours to keep

Context Mode Engine is source-available under the Elastic License 2.0. Use it, copy it, change it and share it at zero cost, for as long as you follow the licence terms. It runs on your machine, sends zero usage data, 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.

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.