Purpose
Runcap (repository name ai-agent-manager) is a local-first control layer for AI coding agents, aimed at developers who need to control AI coding spending, constrain task scope, and require evidence before merging. It does not provide model access; instead, it intercepts requests from your own agents (such as Claude Code, Codex, or any script calling the OpenAI/Anthropic API) through a local gateway to perform metering, price limiting, and compression.
Main capabilities
- Hard spending caps (gateway): Point OpenAI- or Anthropic-compatible tools at the local gateway, record real token usage, price it according to the source table, and immediately block calls when the daily cap is reached, returning 429 budget_guard. Supports --mock trial use without a key.
- Lossless token compression (built-in, no extra dependencies): Three-layer compression, lossless by construction, without changing natural-language instructions or code semantics. Includes field-by-field trimming (compact JSON re-serialization, folding long logs/stack traces to head and tail, removing trailing whitespace), deduplication of identical blocks, and delta encoding of near-duplicates. Measured: after one edit, rereading a file dropped from 1,186 to 737 prompt tokens (37.9% savings), and the model could still correctly answer about the changed line. Can be disabled with AIM_COMPRESS=off.
- Loop detection: When multiple consecutive prompts are highly similar (default 3 at 92%+ similarity) and the conversation makes no progress, mark loop.looping and issue a warning. Can be disabled with AIM_LOOP_DETECT=off.
- Verified outcome cost (runcap outcome): Calculate Verified Outcome Cost = total run cost / number of tasks that passed verification, generating an outcome receipt with a truthfulness label.
- Verification integrity guard (runcap outcome --guard): Before running, freeze the task contract (baseline commit, SHA-256 of files involved in the verification command, package.json script snapshot, confirm the task currently fails); after running, rerun the verification command from the baseline in a clean working tree, detect behaviors such as test tampering, and give a trust level.
- Task policy and CI execution (runcap mission / policy / ci): In .runcap/mission.yaDeclare task rules in ml, enforce hard limits during execution, generate receipts with policy blocks, and return BLOCKED on violations. CI adjudication mode (runcap ci --mode adjudicate) serves as a required PR check, does not trust agent receipts, recomputes the adjudication in a clean CI job from the PR base commit, and outputs PASS / BLOCKED / HUMAN_APPROVAL_REQUIRED.
How to Use
Install Runcap via the archive and point the agent API calls to the local gateway. Task execution: runcap mission run enforces policy and generates receipts. CI integration: add .runcap/mission.yaml, copy examples/runcap-adjudicate.yml to .github/workflows/, pin the template to Runcap v0.6.0, and when upgrading replace it with the full 40-character commit SHA (do not use floating tags). GitHub branch protection must be configured and hardened (protected branches, required checks, up-to-date before merge, dismiss stale approvals, CODEOWNERS covering workflows/policies/validators/dependencies/protected paths, no bypass for regular authors). When no API key is available, you can try the demo commands offline.
Applicable Scenarios and Limitations
Suitable for developers who already have their own OpenAI or Anthropic API key, their own agent, and are comfortable running CLI and local processes. Runcap does not promise precise cost predictions, only ranges plus hard limits. Spend control applies only to requests routed through Runcap; the CI proof gate independently verifies code changes but does not claim to independently meter all model usage. Currently, managed sync, team pools, organization reporting, and paid plans are not purchasable products. Verified result costs do not include subscriptions, CI minutes, sandbox compute, or human review time.
Project Information
MIT licensed, 100% local. Documentation includes the trust model, incremental encoding evidence (docs/delta-encoding-evidence.md), etc.; no further details beyond the specific links are currently provided.
