MARGINAL

AI agents repeat work that changed nothing. MARGINAL catches it.

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.

Observe first. Prove waste. Earn enforcement.

Open source · Local first · Provider neutral · Zero mandatory runtime dependencies

Try the visual demo → · Quickstart · Architecture · Evidence standard

The problem in one trace

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.

Install for Codex

codex plugin marketplace add SignalLayerLabs/Marginal --ref main
codex plugin add marginal@marginal

Open /hooks and inspect the exact MARGINAL lifecycle hooks before granting trust. The plugin starts globally in Shadow Mode.

codex plugin remove marginal@marginal

With the Python package, explicit Autopilot consent can be recorded with:

marginal install codex --autopilot-consent

How MARGINAL earns authority

1. Observe — collect derived action, outcome, coverage, state and evidence signals locally.
2. Verify — bind decisions, policy identity, trust state and governance cost into Decision Receipts.
3. Earn — require representative local evidence, clean coverage and explicit promotion.
4. Intervene narrowly — only exact eligible actions can be denied under the proven no-progress condition.
5. Recover — immediate retry is allowed; drift, unknown outcomes or failures demote authority and fail open.

Current integrations

Same adapter does not mean same trust. Enforcement evidence stays engine- and repository-specific.

Claude Code

marginal install claude-code
marginal uninstall claude-code

OpenCode

marginal install opencode
marginal uninstall opencode

PrivacyCode

marginal install privacycode
marginal uninstall privacycode

See the integration overview, Claude Code guide, and OpenCode / PrivacyCode guide.

Current enforcement boundary

The Codex integration provides Tool Enforcement, not Full Compute Enforcement.

MARGINAL counts actual avoided actions and recoveries. It does not invent token savings for actions that did not run.

Privacy and integrity

• 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_TELEMETRY exports derived pseudonyms and approved measurements, never raw private payloads.
• AGGREGATE_EXPORT publishes only grouped statistics that meet the configured minimum group size.

Read the privacy model and governance evidence standard.

Controls

marginal status --json
marginal doctor --json
marginal explain DECISION_ID --json
marginal privacy inspect --json

The bundled $marginal skill also exposes native status, doctor, review, promote, and demote operations.

Public evidence

Exploratory SWE-bench Lite smoke

Exploratory 3-task smoke, one paired run per task. The first measured Codex integration validated the integration path; it did not establish performance.

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

Python library

pip install "marginal-ai @ git+https://github.com/SignalLayerLabs/[email protected]"

from marginal import BudgetLimits, Treasury, build_policy

treasury = Treasury(
    BudgetLimits(max_tokens=100_000, max_usd=2.00),
    policy=build_policy("balanced"),
    mode="shadow",
)

Architecture

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.

Documentation

Contributing

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 -q

Read CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.