/context-mode

name: context-mode
description: |
  Use context-mode tools (ctx_execute, ctx_execute_file) instead of Bash/cat when processing
  large outputs. Triggers: "analyze logs", "summarize output", "process data",
  "parse JSON", "filter results", "extract errors", "check build output",
  "analyze dependencies", "process API response", "large file analysis",
  "page snapshot", "browser snapshot", "DOM structure", "inspect page",
  "accessibility tree", "Playwright snapshot",
  "run tests", "test output", "coverage report", "git log", "recent commits",
  "diff between branches", "list containers", "pod status", "disk usage",
  "fetch docs", "API reference", "index documentation",
  "call API", "check response", "query results",
  "find TODOs", "count lines", "codebase statistics", "security audit",
  "outdated packages", "dependency tree", "cloud resources", "CI/CD output".
  Also triggers on ANY MCP tool output that may exceed 20 lines.
  Subagent routing is handled automatically via PreToolUse hook.

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

| Situation | Tool | Example | |-----------|------|---------| | Hit an API endpoint | `ctx_execute` | `fetch('http://localhost:3000/api/orders')` | | Run CLI that returns data | `ctx_execute` | `gh pr list`, `aws s3 ls`, `kubectl get pods` | | Run tests | `ctx_execute` | `npm test`, `pytest`, `go test ./...` | | Git operations | `ctx_execute` | `git log --oneline -50`, `git diff HEAD~5` | | Docker/K8s inspection | `ctx_execute` | `docker stats --no-stream`, `kubectl describe pod` | | Read a log file | `ctx_execute_file` | Parse access.log, error.log, build output | | Read a data file | `ctx_execute_file` | Analyze CSV, JSON, YAML, XML | | Read source code to analyze | `ctx_execute_file` | Count functions, find patterns, extract metrics | | Fetch web docs | `ctx_fetch_and_index` | Index React/Next.js/Zod docs, then search | | Playwright snapshot | `browser_snapshot(filename)` → `ctx_index(path)` → `ctx_search` | Save to file, index server-side, query | | Playwright snapshot (one-shot) | `browser_snapshot(filename)` → `ctx_execute_file(path)` | Save to file, extract in sandbox | | Playwright console/network | `browser_*(filename)` → `ctx_execute_file(path)` | Save to file, analyze in sandbox | | MCP output (already in context) | Use directly | Don't re-index — it's already loaded | | MCP output (need multi-query) | `ctx_execute` to save → `ctx_index(path)` → `ctx_search` | Save to file first, index server-side | | Wipe indexed KB content | `ctx_purge(confirm: true)` | Permanently deletes all indexed content |

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