Context Mode: Default for All Large Output

MANDATORY RULE

<context_mode_logic> <mandatory_rule> Default to context-mode for ALL commands. Only use Bash for guaranteed-small-output operations. </mandatory_rule> </context_mode_logic>

Bash whitelist (safe to run directly):

• File mutations: mkdir, mv, cp, rm, touch, chmod
• Git writes: git add, git commit, git push, git checkout, git branch, git merge
• Navigation: cd, pwd, which
• Process control: kill, pkill
• Package management: npm install, npm publish, pip install
• Simple output: echo, printf

Everything else → ctx_execute or ctx_execute_file. Any command that reads, queries, fetches, lists, logs, tests, builds, diffs, inspects, or calls an external service. This includes ALL CLIs (gh, aws, kubectl, docker, terraform, wrangler, fly, heroku, gcloud, etc.) — there are thousands and we cannot list them all.

When uncertain, use context-mode. Every KB of unnecessary context reduces the quality and speed of the entire session.

Decision Tree

About to run a command / read a file / call an API?
│
├── Command is on the Bash whitelist (file mutations, git writes, navigation, echo)?
│   └── Use Bash
│
├── Output MIGHT be large or you're UNSURE?
│   └── Use context-mode ctx_execute or ctx_execute_file
│
├── Fetching web documentation or HTML page?
│   └── Use ctx_fetch_and_index → ctx_search
│
├── Using Playwright (navigate, snapshot, console, network)?
│   └── ALWAYS use filename parameter to save to file, then:
│       browser_snapshot(filename) → ctx_index(path) or ctx_execute_file(path)
│       browser_console_messages(filename) → ctx_execute_file(path)
│       browser_network_requests(filename) → ctx_execute_file(path)
│       ⚠ browser_navigate returns a snapshot automatically — ignore it,
│         use browser_snapshot(filename) for any inspection.
│       ⚠ Playwright MCP uses a SINGLE browser instance — NOT parallel-safe.
│         For parallel browser ops, use agent-browser via execute instead.
│
├── Using agent-browser (parallel-safe browser automation)?
│   └── Run via execute (shell) — each call gets its own subprocess:
│       execute("agent-browser open example.com && agent-browser snapshot -i -c")
│       ✓ Supports sessions for isolated browser instances
│       ✓ Safe for parallel subagent execution
│       ✓ Lightweight accessibility tree with ref-based interaction
│
├── Processing output from another MCP tool (Context7, GitHub API, etc.)?
│   ├── Output already in context from a previous tool call?
│   │   └── Use it directly. Do NOT re-index with ctx_index(content: ...).
│   ├── Need to search the output multiple times?
│   │   └── Save to file via ctx_execute, then ctx_index(path) → ctx_search
│   └── One-shot extraction?
│       └── Save to file via ctx_execute, then ctx_execute_file(path)
│
└── Reading a file to analyze/summarize (not edit)?
    └── Use ctx_execute_file (file loads into FILE_CONTENT, not context)

When to Use Each Tool

Automatic Triggers

Use context-mode for ANY of these, without being asked:

• API debugging: "hit this endpoint", "call the API", "check the response", "find the bug in the response"
• Log analysis: "check the logs", "what errors", "read access.log", "debug the 500s"
• Test runs: "run the tests", "check if tests pass", "test suite output"
• Git history: "show recent commits", "git log", "what changed", "diff between branches"
• Data inspection: "look at the CSV", "parse the JSON", "analyze the config"
• Infrastructure: "list containers", "check pods", "S3 buckets", "show running services"
• Dependency audit: "check dependencies", "outdated packages", "security audit"
• Build output: "build the project", "check for warnings", "compile errors"
• Code metrics: "count lines", "find TODOs", "function count", "analyze codebase"
• Web docs lookup: "look up the docs", "check the API reference", "find examples"

Language Selection

Search Query Strategy

• BM25 uses OR semantics — results matching more terms rank higher automatically
• Use 2-4 specific technical terms per query
• Always use source parameter when multiple docs are indexed to avoid cross-source contamination
  • Partial match works: source: "Node" matches "Node.js v22 CHANGELOG"
• Always use queries array — batch ALL search questions in ONE call:
  • ctx_search(queries: ["transform pipe", "refine superRefine", "coerce codec"], source: "Zod")
  • NEVER make multiple separate ctx_search() calls — put all queries in one array

External Documentation

• Always use ctx_fetch_and_index for external docs — NEVER cat or ctx_execute with local paths for packages you don't own
• For GitHub-hosted projects, use the raw URL: https://raw.githubusercontent.com/org/repo/main/CHANGELOG.md
• After indexing, use the source parameter in search to scope results to that specific document

Critical Rules

1. Always console.log/print your findings. stdout is all that enters context. No output = wasted call.
2. Write analysis code, not just data dumps. Don't console.log(JSON.stringify(data)) — analyze first, print findings.
3. Be specific in output. Print bug details with IDs, line numbers, exact values — not just counts.
4. For files you need to EDIT: Use the normal Read tool. context-mode is for analysis, not editing.
5. For Bash whitelist commands only: Use Bash for file mutations, git writes, navigation, process control, package install, and echo. Everything else goes through context-mode.
6. Never use ctx_index(content: large_data). Use ctx_index(path: ...) to read files server-side. The content parameter sends data through context as a tool parameter — use it only for small inline text.
7. Always use filename parameter on Playwright tools (browser_snapshot, browser_console_messages, browser_network_requests). Without it, the full output enters context.
8. Don't re-index data already in context. If an MCP tool returned da