Your AI coding agent is burning context on test output. ContextCap stops that.
When an AI coding agent (OpenCode, Claude Code, Cursor, …) runs a shell command — most expensively a failing test suite — the full raw stdout/stderr gets dumped straight into the model's context window. A single failing Jest suite with a long stack trace can burn thousands of tokens on noise the agent never needed, crowding out reasoning space and inflating cost per turn.
ContextCap intercepts the command, writes the full output to a timestamped log file on disk, and prints only a small, useful summary back to the agent. If the agent needs more detail, it queries the log file selectively — never in bulk.
agent ──► contextcap run <command> ──► full output ──► .contextcap/logs/*.log
│
└──► capped summary (pass/fail/skip + first N failures) ──► agent
agent ──► contextcap query --pattern "..." ──► searches the log, sandboxed
ContextCap is built on a strict separation of concerns. Each layer knows nothing about the one above it:
- Core engine (
@contextcap/core) — a standalone CLI that wraps an arbitrary shell command, captures stdout/stderr with the real exit code, writes a timestamped log, and prints a capped summary. Zero knowledge of any AI agent. This is the only piece that runs commands. - Adapters (
@contextcap/adapter-*) — small pure-data modules that teach the engine how to recognise failure patterns for a specific test runner. The core ships with one generic regex-based fallback adapter so it's useful on day one. Adapters are opt-in and community-contributable. - Integrations (
@contextcap/integration-*) — thin shims, one per AI host, that translate "agent wants to run a command" into "run it through the core engine instead." Each integration is small enough to read in two minutes.
The tool that runs commands and writes logs knows nothing about AI agents. The tool that talks to AI agents knows nothing about test runners. Violate this and you've built a plugin, not an open-source tool.
npm install -g @contextcap/core# Run a command through ContextCap
contextcap run "npm test"
# Search the most recent log for a pattern (sandboxed to the log directory)
contextcap query --pattern "TypeError" --context 3
# Re-print the last run's summary
contextcap query --summary
# Delete logs older than 24 hours
contextcap rotate --max-age 24If you're writing an adapter or an integration, read these first:
docs/OUTPUT_CONTRACT.md— the versioned summary format the engine prints. Treat as a public API.docs/ADAPTER_CONTRACT.md— how to write a pure-data adapter.docs/INTEGRATION_CONTRACT.md— how to write a host shim.
MIT.