-
+
# MARGINAL
-### Evidence-based compute governance for AI agents
+## AI agents repeat work that changed nothing. **MARGINAL catches it.**
-**MARGINAL watches agent work, detects proven no-progress repetition, and earns limited authority to stop 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
-[Quickstart](docs/getting-started/quickstart.md) · [Architecture](docs/product/architecture.md) ·
-[Evidence standard](docs/evaluation/governance-evidence.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
+[**Try the visual demo →**](https://signallayerlabs.github.io/Marginal/#demo) · [Quickstart](docs/getting-started/quickstart.md) · [Architecture](docs/product/architecture.md) · [Evidence standard](docs/evaluation/governance-evidence.md)
[](https://github.com/SignalLayerLabs/Marginal/actions/workflows/ci.yml)
[](https://github.com/SignalLayerLabs/Marginal/actions/workflows/codeql.yml)
@@ -23,151 +24,95 @@ Open source · Local first · Provider neutral · Zero mandatory runtime depende
---
-## What MARGINAL does
-
-- Observes tool actions, outcomes, workspace state, and new evidence.
-- Distinguishes useful repetition from the same successful action repeated without progress.
-- Records decisions in a verifiable, hash-chained Decision Ledger.
-- Grants authority gradually and removes it when evidence, identity, capability, or integrity changes.
+## The problem in one trace
-MARGINAL does not assume that more calls are wasteful. Missing or ambiguous evidence fails open.
-
-## Current integrations
-
-| Engine | Capability | Integration |
-|---|---|---|
-| **Codex** | **Tool Enforcement** | Native plugin. Shadow Mode by default; enforcement requires local Earned Enforcement evidence. |
-| **Claude Code** | **Observe** | Native plugin using Claude Code hooks. Records engine-declared success/failure without changing the next model action. |
-| **OpenCode** | **Observe** | In-process JavaScript plugin with a persistent stdio bridge to the provider-neutral runtime. |
-| **PrivacyCode** | **Observe** | OpenCode-compatible install target with a distinct engine identity, ledger root, and trust evidence. |
+```text
+WITHOUT MARGINAL WITH MARGINAL
-`Observe` integrations record evidence and recommendations but cannot block. A compatible install target
-may share an adapter, but it never shares earned trust: **same adapter does not mean same enforcement
-evidence**.
+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
+```
-## Native integrations
+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**.
-### Codex
+> **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 the native plugin from the repository:
+## Install for Codex
```bash
codex plugin marketplace add SignalLayerLabs/Marginal --ref main
codex plugin add marginal@marginal
```
-The plugin starts globally in **Shadow Mode**. Open `/hooks` in Codex and approve the exact hook
-definitions after inspection. One local Python 3.10–3.13 interpreter is required; the launcher can
-find a compatible interpreter even when macOS resolves `python3` to an older Xcode runtime.
-
-Remove the plugin with:
+Open `/hooks` and inspect the exact MARGINAL lifecycle hooks before granting trust. The plugin starts globally in **Shadow Mode**.
```bash
codex plugin remove marginal@marginal
```
-If the Python package is installed, the equivalent installer can also record explicit Autopilot
-consent:
+With the Python package, explicit Autopilot consent can be recorded with:
```bash
marginal install codex --autopilot-consent
```
-Installation alone never enables enforcement. Earned Enforcement requires verified evidence and
-explicit promotion.
+## How MARGINAL earns authority
-### Claude Code
+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
+
+| 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. |
-With the Python CLI installed:
+Same adapter does **not** mean same trust. Enforcement evidence stays engine- and repository-specific.
+### Claude Code
```bash
marginal install claude-code
marginal uninstall claude-code
```
-Claude Code is **Observe-only** today. Its hooks expose separate success and failure events, so those
-outcomes are engine-declared rather than inferred from tool output.
-
### OpenCode
-
```bash
marginal install opencode
marginal uninstall opencode
```
-OpenCode is **Observe-only**. The JavaScript plugin runs in the engine process and communicates with one
-long-running local MARGINAL bridge over stdio. Shell exit codes can prove shell success/failure; outcomes
-without a reliable engine signal remain `unknown`.
-
### PrivacyCode
-
```bash
marginal install privacycode
marginal uninstall privacycode
```
-PrivacyCode reuses the OpenCode plugin contract but keeps a distinct engine label, installation path,
-ledger root, and evidence history. Compatibility is validated, not assumed permanently; a protocol
-divergence requires a separate adapter.
-
-See the [integration overview](docs/integrations/overview.md), [Claude Code guide](docs/integrations/claude-code.md),
-and [OpenCode / PrivacyCode guide](docs/integrations/opencode.md).
+See the [integration overview](docs/integrations/overview.md), [Claude Code guide](docs/integrations/claude-code.md), and [OpenCode / PrivacyCode guide](docs/integrations/opencode.md).
-## How Autopilot works
+## Current enforcement boundary
-1. **Observe.** Hooks collect derived state, outcome, and coverage signals in Shadow Mode.
-2. **Verify.** Decision Receipts bind the decision, policy, trust state, and governance cost.
-3. **Earn authority.** Promotion requires explicit consent, a valid receipt, and a verified ledger range.
-4. **Intervene narrowly.** Only an exact eligible action with two prior successes and no state or evidence change can be denied on the third attempt.
-5. **Recover.** An immediate retry is allowed after a deny. Failures, unknown outcomes, drift, or integrity errors demote authority and fail open.
-
-Authority is contextual, not permanent. The Trust Engine evaluates sample size, coverage, harmful
-outcomes, regret, governance tax, recency, policy identity, and available adapter capabilities.
-
-The promotion gate assumes a non-adversarial, same-user trust domain. Receipt and ledger hashes
-detect corruption and make decisions reproducible; they do not prove authorship or stop the agent,
-a prompt-injected tool, or another same-user process from rewriting local state. Do not treat local
-Earned Enforcement as a security boundary against software running as the same OS user.
-
-## User intent and controls
-
-Codex user prompts can express deliberate repeat intent in English or Italian, including `repeat`,
-`force`, and `ripeti`. Negated or ambiguous phrases fail open. The prompt is processed in memory;
-its text and hash are not written to evidence.
-
-With the Python CLI:
-
-```bash
-marginal status --json
-marginal doctor --json
-marginal explain DECISION_ID --json
-marginal privacy inspect --json
-```
-
-- `status` separates configured mode from effective authority and lists promotion blockers.
-- `doctor` checks runtime, hooks, schemas, policy identity, ledger integrity, and file permissions.
-- `explain` returns the redacted evidence behind one decision.
-- `privacy inspect` lists every persisted data category.
-
-The bundled `$marginal` skill exposes native `status`, `doctor`, `review`, `promote`, and `demote`
-operations without requiring a global executable.
-
-## Enforcement boundary
-
-The current Codex integration provides **Tool Enforcement**, not Full Compute Enforcement.
+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 and repetition proof reset |
+| 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.
+MARGINAL counts actual avoided actions and recoveries. It does not invent token savings for actions that did not run.
## Privacy and integrity
@@ -176,46 +121,48 @@ that did not run.
- 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 tool action.
+- 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](docs/operations/privacy.md) and
-[governance evidence standard](docs/evaluation/governance-evidence.md).
+Read the [privacy model](docs/operations/privacy.md) and [governance evidence standard](docs/evaluation/governance-evidence.md).
-## Measured evidence
+## Controls
-**Exploratory 3-task smoke, one paired run per task.** This SWE-bench Lite result validates the
-integration path; it does not establish performance.
+```bash
+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.
| 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 |
-| Effective latency | 593.11 s | 565.77 s | 4.61% lower |
-| Tool calls | 33 | 32 | 3.03% fewer |
+| 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 |
-The observed token difference is 24.93%, but neither lane resolved a task.
-
-**No deny was applied in these three agent trajectories.** The difference therefore cannot be
-attributed to MARGINAL and is not a useful-token-saving claim. Tokens per resolved task remain
-undefined.
+**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](benchmarks/swebench_lite/PUBLIC_BENCHMARK.md) · [Raw JSON](benchmarks/swebench_lite/public-benchmark.json) ·
-[Evidence bundle](benchmarks/swebench_lite/evidence/smoke-2026-08-11-dbce533/) · [Protocol](benchmarks/swebench_lite/README.md)
+[Public report](benchmarks/swebench_lite/PUBLIC_BENCHMARK.md) · [Raw JSON](benchmarks/swebench_lite/public-benchmark.json) · [Evidence bundle](benchmarks/swebench_lite/evidence/smoke-2026-08-11-dbce533/) · [Protocol](benchmarks/swebench_lite/README.md)
## Python library
-Install the current tagged version:
-
```bash
pip install "marginal-ai @ git+https://github.com/SignalLayerLabs/Marginal.git@v0.3.3"
```
-Minimal Shadow Mode example:
-
```python
from marginal import BudgetLimits, Treasury, build_policy
@@ -226,9 +173,6 @@ treasury = Treasury(
)
```
-Start new integrations in Shadow Mode. Promote only after representative evidence shows that the
-policy preserves verified quality.
-
## Architecture
```text
@@ -239,11 +183,10 @@ Universal Agent Protocol
├── Treasury and policy
├── progress and utility evidence
├── Trust Engine and authority levels
- └── Decision Receipts and governance ledger
+ └── Decision Receipts and Decision Ledger
```
-Adapters own native interception. The provider-neutral core owns policy, accounting, trust, and
-evidence semantics. See the [architecture guide](docs/product/architecture.md).
+Adapters own native interception. The provider-neutral core owns policy, accounting, trust and evidence semantics. See the [architecture guide](docs/product/architecture.md).
## Documentation
@@ -260,8 +203,7 @@ evidence semantics. See the [architecture guide](docs/product/architecture.md).
## Contributing
-Contributions and falsifiable criticism are welcome. Performance changes should include the
-evidence that could prove them wrong.
+Contributions and falsifiable criticism are welcome. Performance changes should include the evidence that could prove them wrong.
```bash
ruff format --check .
@@ -273,5 +215,4 @@ pytest -q
Read [CONTRIBUTING.md](CONTRIBUTING.md).
## License
-
Apache-2.0. See [LICENSE](LICENSE).
diff --git a/assets/marginal-readme-hero.svg b/assets/marginal-readme-hero.svg
new file mode 100644
index 0000000..01c47f4
--- /dev/null
+++ b/assets/marginal-readme-hero.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/superpowers/plans/2026-08-18-marketing-refactor.md b/docs/superpowers/plans/2026-08-18-marketing-refactor.md
new file mode 100644
index 0000000..185b08d
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-18-marketing-refactor.md
@@ -0,0 +1,47 @@
+# MARGINAL Marketing Refactor Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make MARGINAL obvious in five seconds, visually demonstrable at €0 inference cost, SEO-complete and claim-safe.
+
+**Architecture:** Message-first static site, dedicated deterministic demo, marketing-first README, local SVG/PNG assets and lightweight vanilla JS.
+
+**Tech Stack:** HTML5, CSS3, vanilla JavaScript, SVG, PNG, Markdown, GitHub Pages.
+
+**Spec:** `docs/superpowers/specs/2026-08-18-marketing-refactor-design.md`
+
+## Global Constraints
+- Preserve evidence-first claim discipline.
+- No causal token-savings claim from the historical smoke.
+- Codex = Tool Enforcement; Claude Code/OpenCode/PrivacyCode = Observe-only.
+- No new site runtime dependencies.
+- Respect `prefers-reduced-motion`.
+
+---
+
+### Task 1: Acceptance tests
+- [x] Add structural SEO/copy/truthfulness/asset/accessibility tests.
+- [x] Verify RED before implementation.
+
+### Task 2: Homepage
+- [x] Build Hero → Demo → How it works → Integrations → Proof → Research → FAQ → CTA.
+- [x] Add accessible nav, copy CTA and deterministic trace replay.
+
+### Task 3: Visual assets
+- [x] Add 1280×640 README hero SVG.
+- [x] Add 1200×630 OG/Twitter PNG.
+- [x] Add shareable `/demo/` page.
+
+### Task 4: README
+- [x] Put concrete problem, visual explanation and install above technical detail.
+- [x] Keep exact enforcement/privacy/research boundaries.
+
+### Task 5: SEO + deploy pack
+- [x] Update robots/sitemap.
+- [x] Add apply, verify and deploy instructions.
+
+### Task 6: Verification
+- [x] Marketing acceptance tests pass.
+- [x] JS syntax passes.
+- [x] Static link/JSON-LD checks pass.
+- [x] ZIP integrity checked.
diff --git a/docs/superpowers/specs/2026-08-18-marketing-refactor-design.md b/docs/superpowers/specs/2026-08-18-marketing-refactor-design.md
new file mode 100644
index 0000000..d5880c9
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-18-marketing-refactor-design.md
@@ -0,0 +1,28 @@
+# MARGINAL Marketing Refactor — Design Specification
+
+## Goal
+Make MARGINAL understandable in five seconds and compelling enough to earn GitHub stars without overstating unproven performance claims.
+
+## Positioning
+Primary category: **runtime governor for AI coding agents**. Primary problem: **AI agents can repeat work without making progress**. Primary promise: **MARGINAL detects no-progress repetition**. Primary differentiator: **MARGINAL starts by observing and must earn limited enforcement authority from evidence.**
+
+Canonical message stack:
+1. **AI agents repeat work that changed nothing.**
+2. **MARGINAL catches it.**
+3. **Observe first. Prove waste. Earn enforcement.**
+
+## Experience hierarchy
+Hero → deterministic mechanism demo → How it works → Integrations → Proof → Research → FAQ → Install CTA.
+
+## Claim discipline
+- Never claim the historical 24.93% token delta was caused by MARGINAL.
+- State the smoke was 0/3 vs 0/3 and no deny was applied.
+- Label the deterministic visual demo as not a production benchmark.
+- Codex is Tool Enforcement, never Full Compute Enforcement.
+- Claude Code, OpenCode and PrivacyCode are Observe-only.
+
+## SEO
+One H1; canonical `https://signallayerlabs.github.io/Marginal/`; intent-focused title/description; OG/Twitter 1200×630 image; SoftwareApplication + FAQPage JSON-LD; semantic sections; robots.txt and sitemap.xml.
+
+## Visual language
+Dark technical canvas, acid-green action accent, red only for waste, mono trace labels, strong contrast, responsive panels, no external font dependency, motion disabled under prefers-reduced-motion.
diff --git a/site/app.js b/site/app.js
index baad58e..d94d928 100644
--- a/site/app.js
+++ b/site/app.js
@@ -1,2 +1 @@
-const button=document.querySelector(".nav-toggle");const links=document.querySelector(".nav-links");
-if(button&&links){button.addEventListener("click",()=>{const open=links.classList.toggle("open");button.setAttribute("aria-expanded",String(open))});links.addEventListener("click",event=>{if(event.target instanceof HTMLAnchorElement){links.classList.remove("open");button.setAttribute("aria-expanded","false")}})}
\ No newline at end of file
+const menuButton=document.querySelector('.nav-toggle');const menu=document.querySelector('.nav-links');if(menuButton&&menu){menuButton.addEventListener('click',()=>{const open=menu.classList.toggle('open');menuButton.setAttribute('aria-expanded',String(open))});menu.addEventListener('click',e=>{if(e.target instanceof HTMLAnchorElement){menu.classList.remove('open');menuButton.setAttribute('aria-expanded','false')}})}document.querySelectorAll('[data-copy]').forEach(button=>{button.addEventListener('click',async()=>{const target=document.querySelector(button.getAttribute('data-copy'));if(!target)return;try{await navigator.clipboard.writeText(target.textContent.trim());button.textContent='Copied';setTimeout(()=>button.textContent='Copy',1400)}catch{button.textContent='Select';const range=document.createRange();range.selectNodeContents(target);const selection=window.getSelection();selection.removeAllRanges();selection.addRange(range)}})});const play=document.querySelector('[data-demo-play]');const rows=[...document.querySelectorAll('[data-demo-step]')];let timer=null;function resetDemo(){rows.forEach(row=>row.classList.remove('active'))}function playDemo(){if(timer)clearInterval(timer);resetDemo();let i=0;rows[0]?.classList.add('active');timer=setInterval(()=>{i+=1;if(i>=rows.length){clearInterval(timer);timer=null;return}rows[i].classList.add('active')},420)}if(play)play.addEventListener('click',playDemo);if(!window.matchMedia('(prefers-reduced-motion: reduce)').matches){const demo=document.querySelector('#demo');if(demo){const observer=new IntersectionObserver(entries=>{if(entries.some(e=>e.isIntersecting)){playDemo();observer.disconnect()}},{threshold:.35});observer.observe(demo)}}
\ No newline at end of file
diff --git a/site/assets/marginal-social-card.png b/site/assets/marginal-social-card.png
new file mode 100644
index 0000000..44525e7
Binary files /dev/null and b/site/assets/marginal-social-card.png differ
diff --git a/site/demo/index.html b/site/demo/index.html
new file mode 100644
index 0000000..2299b7d
--- /dev/null
+++ b/site/demo/index.html
@@ -0,0 +1 @@
+MARGINAL Demo — See a No-Progress AI Agent LoopSkip to content
Runtime governor for AI coding agents
AI agents repeat work that changed nothing.MARGINAL catches it.
MARGINAL watches tool actions, outcomes and workspace evidence. When the same successful action repeats with no observable progress, it can identify the loop — without assuming every retry is waste.
*Only after local Earned Enforcement. Otherwise MARGINAL stays advisory.Fails open on ambiguity.
10-second mechanism demo
Activity is not the same thing as progress.
Same action. Same state. No new evidence. That is the signal MARGINAL cares about. This deterministic visual is a mechanism demonstration, not a production benchmark.
Installation does not equal authority. MARGINAL separates observation, proof and enforcement so an efficiency tool cannot casually become a correctness risk.
01 / OBSERVE
Watch
Collect derived action, outcome, coverage, workspace-state and evidence signals locally.
02 / PROVE
Compare
Look for repeated successful actions where observable state and useful evidence did not change.
03 / EARN
Build trust
Require representative local evidence, clean coverage and explicit promotion before blocking.
04 / INTERVENE
Stop narrowly
Only eligible action families can be denied, and only under the exact proven no-progress condition.
05 / RECOVER
Fail open
Unknown outcomes, drift, integrity failures or changed evidence remove pressure and restore allowance.
Works alongside coding agents
One governance core. Conservative engine boundaries.
MARGINAL is not another coding agent. It sits beside supported runtimes and turns native lifecycle signals into the same provider-neutral evidence model.
Tool Enforcement
Codex
Native plugin. Shadow Mode by default; repository-local Earned Enforcement is intentionally narrow.
Observe-only
Claude Code
Native hooks record engine-declared success and failure without changing the next model action.
Observe-only
OpenCode
In-process JavaScript plugin with a persistent stdio bridge to the provider-neutral runtime.
Observe-only
PrivacyCode
OpenCode-compatible target with its own engine identity, ledger root and trust evidence.
Designed to be falsifiable
MARGINAL has to justify its own overhead, too.
The project treats governance cost, harmful interventions and preserved quality as first-class measurements — not footnotes.
01
Shadow first
New installations observe before blocking. Lack of evidence is not permission.
02
Decision ledger
Canonical records are hash chained so decisions can be reproduced and integrity drift detected.
03
Local-first privacy
Raw prompts, source, commands, outputs, transcripts and credentials are not evidence fields.
04
Fail open
Ambiguous or unsupported outcomes do not become evidence for blocking.
05
Explicit boundaries
Tool Enforcement is not presented as Full Compute Enforcement. Capabilities stay adapter-specific.
06
Graceful irrelevance
If a future agent is already efficient, MARGINAL should measure that and get out of the way.
Public evidence, without marketing math
The first smoke validated the integration — not the savings claim.
We keep negative and inconclusive results public because MARGINAL's credibility depends on separating observation from causation.
Exploratory SWE-bench Lite smoke
Three matched tasks, one paired run per task. Both lanes resolved 0/3. A 24.93% token difference was observed, but No deny was applied in the trajectories. Therefore the difference is not attributed to MARGINAL and is not a support claim.
The full report, raw JSON, protocol and evidence bundle remain public in the repository.
Today, Codex Tool Enforcement is deliberately narrow. Exact eligible workspace-local reads can become denyable after verified repeated success with no state or evidence change. Generic shell, tests, search, writes, network and unknown MCP paths remain observe/recommend only.
Is MARGINAL a security product?
No. It is an efficiency governor, not a security boundary against software running as the same OS user.
Does it work with Claude Code?
Yes in Observe-only mode. Claude Code hooks can record engine-declared success/failure and feed the same evidence model, but the integration does not block actions today.
Why not just cap tokens?
A fixed cap cannot distinguish useful verification from repeated no-progress work. MARGINAL focuses on the marginal value of the next action and on observable evidence, not only the size of a budget.
Open source · Apache-2.0
If your coding agent loops, make the loop prove it is useful.
Clone it, inspect the hooks, run Shadow Mode, challenge the evidence model — and star the repo if you want this idea to keep moving.
\ No newline at end of file
diff --git a/site/index.html b/site/index.html
index bc6e18b..020b50b 100644
--- a/site/index.html
+++ b/site/index.html
@@ -1,225 +1 @@
-
-
-
-
-
- MARGINAL — Evidence-Driven Compute Governance for AI Agents
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Skip to content
-
-
-
-
-
-
-
-
-
First measured Codex integration
-
Measured OFF vs ON. Correctness first.
-
Exploratory 3-task smoke, one paired run per task. Codex CLI 0.147.0 with GPT-5.6-sol, identical prompts and limits, verified in official SWE-bench Lite task environments on Modal.
Tool Enforcement, never an overstated Full Compute Enforcement claim. Repository blocking must earn a local evidence receipt and demotes automatically on drift. Universal directory review is pending; the Git marketplace works now.
Scope matters. This smoke validates the integration and supplies an early paired observation; n=3 is too small for a general performance claim. Neither lane resolved a task, so efficiency per resolved task is undefined. No deny was applied in these three agent trajectories, so the observed token difference is not evidence that a deny caused the saving.
The next action should add evidence, not just activity.
-
MARGINAL evaluates whether another model call, tool call, retry, verification or reviewer is likely to add enough value to justify its cost — and accounts for the cost of making that decision.
The question mark matters: enforcement is earned by evidence, not assumed by the demo.
-
-
-
-
-
-
Multi-engine runtime
-
One governance core. Engine-specific evidence boundaries.
-
Adapters translate native lifecycle events into the same provider-neutral runtime. Capability labels stay conservative: sharing an adapter never transfers earned trust between engines.
Not “models waste tokens.” Diminishing marginal value.
-
-
-
Coding agents can spend compute on actions whose incremental value becomes unclear. A repeated action is not automatically waste: another test may be exactly what a risky patch needs.
-
MARGINAL looks for a stronger pattern: same semantic action + unchanged observable state + no new evidence. That is provider-neutral and remains meaningful even when models improve.
-
-
-
-
-
-
Proof before claims
-
MARGINAL must earn its own compute.
-
Matched OFF/ON evaluation is the product test. Saving agent tokens is insufficient if governance overhead, quality loss or false stops erase the benefit.
-
-
- 01
Verified quality
Same verifier, predefined non-inferiority margin, regressions and recoveries exposed.
- 02
Gross savings
Agent workload change before counting MARGINAL's own cost.
- 03
Net savings
Effective tokens, USD and latency after the governance tax. This is the claim surface.
- 04
Repeated calls
Shows whether behavior changed or the system simply moved cost somewhere else.
- 05
False stops
Explicitly reviewed deny recommendations that would have blocked helpful work.
- 06
Uncertainty
Repeated runs and bootstrap intervals separate a stable effect from one lucky trajectory.
-
-
- Primary target
- Minimize effective compute per verified successful task, subject to quality and false-stop constraints.
-
-
-
-
-
-
Graceful irrelevance
-
What if GPT-5.7 — or any future model — is already efficient?
-
-
-
Then MARGINAL should get out of the way. The evaluator now distinguishes gross from net savings and can classify a configuration as pass_through when the governor does not demonstrate enough net value.
-
$ marginal public-eval baseline.jsonl marginal.jsonlintervention.status: pass_throughNo positive net intervention value demonstrated.
-
A negative or neutral benchmark is a valid result. The project should not manufacture a reason to intervene simply to justify its own existence.
-
-
-
-
-
New control
State-aware diminishing returns, without a GPT-specific patch.
-
-
-
Same semantic keye.g. verify the same artifact for the same purpose
-
Same state hashthe underlying workspace has not changed
-
No new evidencethe previous pass did not change the evidence state
-
Repeat count risesexpected gain decays until a configured stop threshold
-
-
-
The detector is opt-in. Missing state fails open. Changed state or new evidence resets the pressure. That keeps the mechanism conservative while real agent telemetry is collected.
-
Exact duplicate prevention still exists. Diminishing-return control adds a semantic layer for allowed retries and verification loops where fingerprints can legitimately differ.
Feedback changes the product only when the reasoning survives review.
-
- Accepted
Show OFF vs ON benchmarks
Matched runs are required for performance claims. The 10-task canary remains engineering validation, not marketing evidence.
- Accepted
Future models may reduce the benefit
Converted into Graceful Irrelevance: MARGINAL must demonstrate positive net value for the workload in front of it.
- Partially accepted
“Less slop” on the website
The technical concepts stay, but the landing page now starts with a concrete failure mode and proof standard before architecture theory.
- Rejected
Providers intentionally preserve waste
There is no evidence needed or offered for that claim. MARGINAL is justified by user-controlled economics and observability, not provider motive speculation.
-
-
-
-
-
Benchmark discipline
One benchmark is a surface, not ground truth.
-
-
The requested SWE-bench Pro comparison can be useful because it is recognizable and gives the community a common reference. It should still be versioned, audited and accompanied by task-quality notes.
MARGINAL-specific evaluation should also target the behavior the product claims to change: redundant same-state actions, repeated verification, overhead, false stops and verified outcomes.
Codex, Claude Code, OpenCode and PrivacyCode now reach the same governance core through capability-aware integrations. The next gate is cross-engine conformance and causal intervention evidence, not broader claims.
-
-
-
-
-
+MARGINAL — Stop No-Progress Loops in AI Coding AgentsSkip to content
Runtime governor for AI coding agents
AI agents repeat work that changed nothing.MARGINAL catches it.
MARGINAL watches tool actions, outcomes and workspace evidence. When the same successful action repeats with no observable progress, it can identify the loop — without assuming every retry is waste.
*Only after local Earned Enforcement. Otherwise MARGINAL stays advisory.Fails open on ambiguity.
10-second mechanism demo
Activity is not the same thing as progress.
Same action. Same state. No new evidence. That is the signal MARGINAL cares about. This deterministic visual is a mechanism demonstration, not a production benchmark.
Installation does not equal authority. MARGINAL separates observation, proof and enforcement so an efficiency tool cannot casually become a correctness risk.
01 / OBSERVE
Watch
Collect derived action, outcome, coverage, workspace-state and evidence signals locally.
02 / PROVE
Compare
Look for repeated successful actions where observable state and useful evidence did not change.
03 / EARN
Build trust
Require representative local evidence, clean coverage and explicit promotion before blocking.
04 / INTERVENE
Stop narrowly
Only eligible action families can be denied, and only under the exact proven no-progress condition.
05 / RECOVER
Fail open
Unknown outcomes, drift, integrity failures or changed evidence remove pressure and restore allowance.
Works alongside coding agents
One governance core. Conservative engine boundaries.
MARGINAL is not another coding agent. It sits beside supported runtimes and turns native lifecycle signals into the same provider-neutral evidence model.
Tool Enforcement
Codex
Native plugin. Shadow Mode by default; repository-local Earned Enforcement is intentionally narrow.
Observe-only
Claude Code
Native hooks record engine-declared success and failure without changing the next model action.
Observe-only
OpenCode
In-process JavaScript plugin with a persistent stdio bridge to the provider-neutral runtime.
Observe-only
PrivacyCode
OpenCode-compatible target with its own engine identity, ledger root and trust evidence.
Designed to be falsifiable
MARGINAL has to justify its own overhead, too.
The project treats governance cost, harmful interventions and preserved quality as first-class measurements — not footnotes.
01
Shadow first
New installations observe before blocking. Lack of evidence is not permission.
02
Decision ledger
Canonical records are hash chained so decisions can be reproduced and integrity drift detected.
03
Local-first privacy
Raw prompts, source, commands, outputs, transcripts and credentials are not evidence fields.
04
Fail open
Ambiguous or unsupported outcomes do not become evidence for blocking.
05
Explicit boundaries
Tool Enforcement is not presented as Full Compute Enforcement. Capabilities stay adapter-specific.
06
Graceful irrelevance
If a future agent is already efficient, MARGINAL should measure that and get out of the way.
Public evidence, without marketing math
The first smoke validated the integration — not the savings claim.
We keep negative and inconclusive results public because MARGINAL's credibility depends on separating observation from causation.
Exploratory SWE-bench Lite smoke
Exploratory 3-task smoke, one paired run per task. Both lanes resolved 0/3. No deny was applied in these three agent trajectories. A 24.93% token difference was observed, so the difference is not attributed to MARGINAL and is not a support claim.
The full report, raw JSON, protocol and evidence bundle remain public in the repository.
Remove cleanly with codex plugin remove marginal@marginal.
FAQ
Fast answers before you clone.
What does MARGINAL actually stop?
Today, Codex Tool Enforcement is deliberately narrow. Exact eligible workspace-local reads can become denyable after verified repeated success with no state or evidence change. Generic shell, tests, search, writes, network and unknown MCP paths remain observe/recommend only.
Is MARGINAL a security product?
No. It is an efficiency governor, not a security boundary against software running as the same OS user.
Does it work with Claude Code?
Yes in Observe-only mode. Claude Code hooks can record engine-declared success/failure and feed the same evidence model, but the integration does not block actions today.
Why not just cap tokens?
A fixed cap cannot distinguish useful verification from repeated no-progress work. MARGINAL focuses on the marginal value of the next action and on observable evidence, not only the size of a budget.
Open source · Apache-2.0
If your coding agent loops, make the loop prove it is useful.
Clone it, inspect the hooks, run Shadow Mode, challenge the evidence model — and star the repo if you want this idea to keep moving.