Open-source runtime governor for AI coding agents. MARGINAL observes agent work, detects proven no-progress repetition, and only earns limited authority to stop it after enough local evidence.
Open source · Local first · Provider neutral · Zero mandatory runtime dependencies
Try the visual demo → · Quickstart · Architecture · Evidence standard
WITHOUT MARGINAL WITH MARGINAL
Read config.py RUN Read config.py NEW EVIDENCE
Read config.py RUN Read config.py VERIFY
Read config.py RUN Read config.py SAME STATE
Read config.py RUN Read config.py STOP CANDIDATE
Read config.py RUN ... BLOCK only if earned
MARGINAL does not assume that repetition is waste. Another read, test, or verification can be exactly what a risky task needs. It looks for a stronger pattern: the same eligible successful action, unchanged observable state, and no new evidence.
Installation is not permission to block your agent. New integrations start in Shadow Mode. Enforcement has to be earned from evidence and can be removed again when evidence, identity, capability, coverage, or integrity changes.
codex plugin marketplace add SignalLayerLabs/Marginal --ref main
codex plugin add marginal@marginalOpen /hooks and inspect the exact MARGINAL lifecycle hooks before granting trust. The plugin starts globally in Shadow Mode.
codex plugin remove marginal@marginalWith the Python package, explicit Autopilot consent can be recorded with:
marginal install codex --autopilot-consent- Observe — collect derived action, outcome, coverage, state and evidence signals locally.
- Verify — bind decisions, policy identity, trust state and governance cost into Decision Receipts.
- Earn — require representative local evidence, clean coverage and explicit promotion.
- Intervene narrowly — only exact eligible actions can be denied under the proven no-progress condition.
- Recover — immediate retry is allowed; drift, unknown outcomes or failures demote authority and fail open.
| Engine | Capability | Current behavior |
|---|---|---|
| Codex | Tool Enforcement | Native plugin. Shadow Mode first; narrow blocking requires repository-local Earned Enforcement evidence. |
| Claude Code | Observe-only | Native hooks record engine-declared success/failure and recommendations; they do not alter the next action. |
| OpenCode | Observe-only | JavaScript plugin + persistent stdio bridge to the provider-neutral runtime. |
| PrivacyCode | Observe-only | OpenCode-compatible target with a distinct engine identity, ledger root and trust history. |
Same adapter does not mean same trust. Enforcement evidence stays engine- and repository-specific.
marginal install claude-code
marginal uninstall claude-codemarginal install opencode
marginal uninstall opencodemarginal install privacycode
marginal uninstall privacycodeSee the integration overview, Claude Code guide, and OpenCode / PrivacyCode guide.
The Codex integration provides Tool Enforcement, not Full Compute Enforcement.
| Action family | Current behavior |
|---|---|
Absolute workspace-local Read / read_file with only a path argument |
Eligible after verified repeated success and no progress |
| User-requested repeat or force | Allowed |
| Polling, waiting, failure, or unknown outcome | Allowed |
| Changed workspace state or evidence | Allowed; repetition proof resets |
| Generic shell, tests, or search | Observe/recommend only |
| Writes, network, deploy, external APIs, unknown MCP | Observe/recommend only |
| MARGINAL status, doctor, demote, and recovery | Trusted control-plane bypass |
MARGINAL counts actual avoided actions and recoveries. It does not invent token savings for actions that did not run.
- Raw prompts, source, commands, outputs, transcripts, and credentials are not evidence fields.
- Private local keys produce domain-separated pseudonyms for low-entropy identifiers.
- The v3 governance ledger links every canonical record to the previous record hash.
- Promotion reads verified ledger payloads, not mutable summary files.
- Ledger files use owner-only permissions, file locking, no-follow opens, and non-destructive quarantine.
- Integration errors demote enforcement and allow the requested action.
SAFE_TELEMETRYexports derived pseudonyms and approved measurements, never raw private payloads.AGGREGATE_EXPORTpublishes only grouped statistics that meet the configured minimum group size.
Read the privacy model and governance evidence standard.
marginal status --json
marginal doctor --json
marginal explain DECISION_ID --json
marginal privacy inspect --jsonThe bundled $marginal skill also exposes native status, doctor, review, promote, and demote operations.
Exploratory 3-task smoke, one paired run per task. The first measured Codex integration validated the integration path; it did not establish performance.
| Metric | Codex OFF | Codex + MARGINAL | Observed change |
|---|---|---|---|
| Verified tasks resolved | 0/3 | 0/3 | 0/3 → 0/3 |
| Effective tokens | 1,098,747 | 824,839 | 24.93% fewer observed |
| Effective latency | 593.11 s | 565.77 s | 4.61% lower observed |
| Tool calls | 33 | 32 | 3.03% fewer observed |
| Governance overhead | — | 0 tokens · $0 · 7.06 s | measured separately |
| Evaluator decision | — | pass_through |
no support claim |
Important: neither lane resolved a task. No deny was applied in these three agent trajectories. The observed 24.93% token difference therefore cannot be attributed to MARGINAL and is not a token-saving claim.
Public report · Raw JSON · Evidence bundle · Protocol
pip install "marginal-ai @ git+https://github.com/SignalLayerLabs/Marginal.git@v0.3.3"from marginal import BudgetLimits, Treasury, build_policy
treasury = Treasury(
BudgetLimits(max_tokens=100_000, max_usd=2.00),
policy=build_policy("balanced"),
mode="shadow",
)Agent adapters
│
Universal Agent Protocol
│
├── Treasury and policy
├── progress and utility evidence
├── Trust Engine and authority levels
└── Decision Receipts and Decision Ledger
Adapters own native interception. The provider-neutral core owns policy, accounting, trust and evidence semantics. See the architecture guide.
| Area | Start here |
|---|---|
| Getting started | Quickstart |
| Product | Concepts · Architecture |
| Codex | Plugin guide · Benchmark readiness |
| Claude Code | Observe plugin |
| OpenCode / PrivacyCode | Observe plugin and compatible targets |
| Evaluation | Benchmarking · Public benchmarks |
| Operations | Privacy · Governance |
| Reference | API · Roadmap |
Contributions and falsifiable criticism are welcome. Performance changes should include the evidence that could prove them wrong.
ruff format --check .
ruff check .
mypy src/marginal
pytest -qRead CONTRIBUTING.md.
Apache-2.0. See LICENSE.