Skip to content

AGENTS.md

Latest commit

 

History

History
65 lines (47 loc) · 4.47 KB

AGENTS.md

File metadata and controls

65 lines (47 loc) · 4.47 KB

context-mode — MANDATORY routing rules

You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.

Think in Code — MANDATORY

When you need to analyze, count, filter, compare, search, parse, transform, or process data: write code that does the work via context-mode_ctx_execute(language, code) and console.log() only the answer. Do NOT read raw data into context to process mentally. Your role is to PROGRAM the analysis, not to COMPUTE it. Write robust, pure JavaScript — no npm dependencies, only Node.js built-ins (fs, path, child_process). Always use try/catch, handle null/undefined, and ensure compatibility with both Node.js and Bun. One script replaces ten tool calls and saves 100x context.

BLOCKED commands — do NOT attempt these

curl / wget — BLOCKED

Any shell command containing curl or wget will be intercepted and blocked by the context-mode plugin. Do NOT retry. Instead use:

  • context-mode_ctx_fetch_and_index(url, source) to fetch and index web pages
  • context-mode_ctx_execute(language: "javascript", code: "const r = await fetch(...)") to run HTTP calls in sandbox

Inline HTTP — BLOCKED

Any shell command containing fetch('http, requests.get(, requests.post(, http.get(, or http.request( will be intercepted and blocked. Do NOT retry with shell. Instead use:

  • context-mode_ctx_execute(language, code) to run HTTP calls in sandbox — only stdout enters context

Direct web fetching — BLOCKED

Do NOT use any direct URL fetching tool. Use the sandbox equivalent. Instead use:

  • context-mode_ctx_fetch_and_index(url, source) then context-mode_ctx_search(queries) to query the indexed content

REDIRECTED tools — use sandbox equivalents

Shell (>20 lines output)

Shell is ONLY for: git, mkdir, rm, mv, cd, ls, npm install, pip install, and other short-output commands. For everything else, use:

  • context-mode_ctx_batch_execute(commands, queries) — run multiple commands + search in ONE call
  • context-mode_ctx_execute(language: "shell", code: "...") — run in sandbox, only stdout enters context

File reading (for analysis)

If you are reading a file to edit it → reading is correct (edit needs content in context). If you are reading to analyze, explore, or summarize → use context-mode_ctx_execute_file(path, language, code) instead. Only your printed summary enters context.

grep / search (large results)

Search results can flood context. Use context-mode_ctx_execute(language: "shell", code: "grep ...") to run searches in sandbox. Only your printed summary enters context.

Tool selection hierarchy

  1. GATHER: context-mode_ctx_batch_execute(commands, queries) — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls. Each command: {label: "descriptive header", command: "..."}. Label becomes FTS5 chunk title — descriptive labels improve search.
  2. FOLLOW-UP: context-mode_ctx_search(queries: ["q1", "q2", ...]) — Query indexed content. Pass ALL questions as array in ONE call.
  3. PROCESSING: context-mode_ctx_execute(language, code) | context-mode_ctx_execute_file(path, language, code) — Sandbox execution. Only stdout enters context.
  4. WEB: context-mode_ctx_fetch_and_index(url, source) then context-mode_ctx_search(queries) — Fetch, chunk, index, query. Raw HTML never enters context.
  5. INDEX: context-mode_ctx_index(content, source) — Store content in FTS5 knowledge base for later search.

Output constraints

  • Keep responses under 500 words.
  • Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
  • When indexing content, use descriptive source labels so others can search(source: "label") later.

ctx commands

Command Action
ctx stats Call the stats MCP tool and display the full output verbatim
ctx doctor Call the doctor MCP tool, run the returned shell command, display as checklist
ctx upgrade Call the upgrade MCP tool, run the returned shell command, display as checklist
ctx purge Call the purge MCP tool with confirm: true. Warns before wiping the knowledge base.

After /clear or /compact: knowledge base and session stats are preserved. Use ctx purge if you want to start fresh.