Run noisy tools. Keep the evidence.
One command to try
Section titled “One command to try”python -m pip install --upgrade ctx-harnessctx run -- pytest -qRun this in a repository with tests. Python 3.11+ is required. Host integration
is optional. The package is ctx-harness; the command is ctx.
A failed command remains a failed command. For a large output, the agent gets
an outcome, a typed digest, and a run: address. Complete captured stdout and
stderr stay in the local store.
Use the address returned by your run:
ctx get run:<id>#stdout --lines 120:180ctx search run:<id>#stdout "AssertionError"<id> is a placeholder. Large retrievals return a bounded region and a
continuation. When the loop is useful, run ctx setup and ctx doctor to
configure a supported coding host.
Pick the job
Section titled “Pick the job”| Job | First tool | Result |
|---|---|---|
| Investigate noisy tests, builds, or logs | ctx run | Outcome and complete captured evidence |
| Locate code before reading files | ctx map, ctx def, ctx refs | Structural views and source coordinates |
| Compare two attempts | ctx diff | Outcome and evidence changes |
| Apply an observed edit and check it | ctx edit replace, ctx edit verify | Plan, apply receipt, and checks bound to exact bytes |
| Resume delegated work | ctx orchestrate, ctx task show | Attempts, recovery, budget, and persisted task state |
Capture and retrieve · Edit and verify · CLI reference
Evidence stays available after the first turn
Section titled “Evidence stays available after the first turn”Typed profiles extract failed test identities, diagnostic locations, unusual log events, and JSON structure. A deterministic renderer fits those facts into a budget and declares what it omitted. There is no model call in this path.
Stored handles identify immutable bytes while retained. Anchored repository reads verify the observed span, relocate unchanged content, or refuse stale coordinates. Model-visible retrieval follows the current redaction policy.
Evidence for the mechanism, and for the trade-off
Section titled “Evidence for the mechanism, and for the trade-off”| Measurement | Finding | What it establishes |
|---|---|---|
| Deterministic field-needle fixture | 302,628 input tokens became 531 output tokens; the quiet target at line 14,238 and a retrieval address remained | Bounded evidence delivery on that fixture |
| Small live canary, three tasks with one repeat | Both arms solved 3/3; the contained arm cost more and took longer | Wrapping small work can be a regression |
| Paired edit and prewalk runner | Requires live paired outcomes before selecting another strategy | A way to measure a policy; no live improvement claim yet |
The needle fixture measures address emission, not a retrieval round trip. Read its receipt, the live counterexamples, and the edit-policy method.
Use containment when output is large, early, or repeatedly carried through a task. Keep small, complete results native. Compare completion, total usage, latency, and retrieval count together.
Know the integration boundary
Section titled “Know the integration boundary”| Entry point | Support |
|---|---|
| Direct CLI | Capture and retrieval without host hooks |
| Claude Code | Command rewrite and oversized-result substitution on supported hooks |
| Codex | Implemented and contract-tested; live CLI receipt pending |
| Antigravity | Deny recognized floods and return a bounded replacement command; no output substitution |
Host capabilities states the exact
contract. Commands retain the invoking user’s authority. Captured artifacts
are local plaintext; redaction of the model’s view is not encryption at rest.
Artifacts become eligible for collection after the configured horizon and remain
until ctx gc runs. The project is pre-1.0.