Overton

Admission control for the coding agents you already pay for.

The Overton window: the range of dispatches currently acceptable.

You have four subscriptions and seven projects. Every orchestrator on your machine — Symphony, Paperclip, gastown, a cron script — will happily spawn an agent the moment it has work, because none of them know what the others are spending. Plan limits are per account. Ambition is per project. Nothing reconciles the two, so every project independently concludes it is on pace while together they are well over.

Overton is a small daemon that does exactly one thing: decide who may run, on whose budget, right now.

$ overton ask sideproject claude-personal
wait 4h12m · sideproject is over its weekly allocation on claude-personal
  account   claude-personal  7d 43% used (target 85, your reserve 15)
  project   sideproject  alloc 17.5 pts  used 21.3 pts
  clock     32% of the window elapsed → allowance 6.4 pts
  reading   ok, 41s old
  over by 14.9 pts. At this rate it finishes the window at 66.5 pts (380% of alloc).

  → try --account claude-work (2.1 of 40.0 pts used)
  → run it anyway with --force — logged, and counted against the next window
  → wait 4d19h — the clock catches up

It does not run agents. No worktrees, no tickets, no PRs, no merge queue. Sixty tools do that and they get better every month. Overton sits in front of them.

Four verbs

Related MCP server: headroom

Why a verdict and not a boolean

"No" has three meanings, and an orchestrator that cannot tell them apart either hammers a gate that will refuse it for four days, or gives up on a window that reopens in ten minutes.

overton ask myproject claude-personal || case $? in
  10) sleep "$(overton ask myproject claude-personal --json | jq .retryAfterSec)" ;;
  12) echo "not allowed on this account, ever"; exit 1 ;;
esac

Install

Needs Bun ≥ 1.3.

git clone https://github.com/hookdump/overton && cd overton
bun install
bun link                    # puts `overton` on your PATH

overton init                # writes ~/.overton/config.yaml
$EDITOR ~/.overton/config.yaml
overton doctor              # verify credentials before you rely on it
overton meter               # poll every account once
overton status

$ overton status
ACCOUNT          PROVIDER   PLAN  7d                5h   READING    CLAIMS
---------------  ---------  ----  ----------------  ---  ---------  ------
claude-personal  anthropic  max   [####------] 43%  14%  3s ago     0/6
claude-work      anthropic  team  [----------] 0%   0%   2s ago     0/6
codex-personal   codex      plus  [----------] 4%   —    20h3m ago  0/6
ollama           unmetered  —     unmetered         —    1s ago     0/2

PROJECT   ACCOUNT          SHARE  USED/ALLOWED  PACE        VERDICT
--------  ---------------  -----  ------------  ----------  -------
loopdeck  claude-personal  75%    0.0/19.2      under 19.2  go
loopdeck  codex-personal   100%   0.0/22.2      under 22.2  go
overton   claude-personal  25%    0.0/6.4       under 6.4   go

Using it

The simplest integration is the wrapper — ask, hold capacity, run, release:

overton run myproject claude-personal -- claude -p "fix issue 42"

Or wire it into whatever you already use. Three surfaces, same answers:

overton ask myproject claude-personal            # CLI, exit code carries the verdict
curl 'localhost:7787/v1/ask?project=P&account=A' # HTTP, always 200, decision in the body
overton mcp                                      # MCP over stdio, so an agent can ask

See docs/04-integration.md for recipes covering Symphony, Paperclip, GitHub Actions and a bare shell loop.

More than one machine

A laptop and a build host sharing one subscription each think they are on pace, for the same reason two orchestrators do. Run Overton on one of them and point the others' CLI at it, and there is a single arbiter again:

# ~/.overton/config.yaml on the laptop
remotes:
  e16:
    url: https://overton.my-tailnet.ts.net
default_remote: e16

$ overton status
overton · e16 https://overton.my-tailnet.ts.net
ACCOUNT          PROVIDER   PLAN  7d                5h  READING  CLAIMS
---------------  ---------  ----  ----------------  --  -------  ------
claude-personal  anthropic  pro   [######----] 57%  0%  2m ago   0/6

Or per invocation: overton --remote e16 status, --remote https://host for one that is not in the config, or $OVERTON_REMOTE for a shell. The name is on every line of output because which Overton answered is not something anyone should have to infer.

The deciding and looking commands go over the wire; meter, daemon, serve, mcp, doctor, plugins, init, paperclip and explain stay local and say why. Nothing ever falls back. An unreachable remote is exit 1 with the URL and the cause — never a plausible table quietly rendered from this machine's own database, which would be wrong in every number and admit it in none.

Exit codes and --json are identical either way, so a script cannot tell the difference. docs/04-integration.md has the precedence rules and the full command split.

Configuration

accounts:
  claude-personal:
    provider: anthropic
    config_dir: ~/.claude-profiles/personal
    weekly_target_pct: 85          # account-wide stop, all projects
    interactive_reserve_pct: 15    # held back for YOUR terminal work
    max_concurrent: 6

projects:
  bigapp:
    roots: [~/Projects/bigapp]
    accounts:
      claude-personal: { weekly_share: 3 }

  sideproject:
    roots: [~/Projects/sideproject]
    accounts:
      claude-personal: { weekly_share: 1 }
      # claude-work is simply not named, so it may never be used

Two things about that file do most of the work.

A share is of the dispatchable pool, not of the plan. 85 − 15 = 70 points are available to agents; bigapp gets ¾ of them and sideproject ¼. Your own interactive work is never what gets squeezed.

Shares are weights, normalised across every project naming the account. You reroute capacity by changing one number and the others absorb it — there is no column to keep summing to 1.0 by hand.

How it decides

    provider ──▶ reading ──▶ epoch ──▶ ledger ──▶ facts ──▶ policy chain ──▶ decision
   (vendor's     (windows,   (one      (per-       (pure     (worst          (verdict,
    authority)   freshness)  window    project     data)     verdict          reason,
                             instance) points)               wins)            retry)

Every policy rules on every request and the worst verdict wins — not the first match. With first-match, correctness depends on the order of a list in a config file, and reordering it to "put the cheap checks first" can silently let a budget policy be pre-empted. With worst-wins, no ordering of any policy set can produce a more permissive answer than its strictest member.

overton explain <project> <account> prints every fact behind a decision.

Extending it

Three registries, one shape. Implement the interface, register it, name it in config.

A policy you add cannot accidentally weaken the built-ins. It can only tighten them, because of worst-wins.

What it deliberately is not

• A harness. It never invokes an agent. overton run spawns your command and gets out of the way.

• An orchestrator. No tickets, no worktrees, no merge queue.

• A fleet TUI. overton status is a table, not a dashboard.

• A proxy. Your credentials are never routed through it; it reads them to ask the vendor about your own usage, nothing more.

• Multi-user. Tailscale is the perimeter. It binds loopback and has no auth.

Honesty rules

A budget arbiter that is confidently wrong is worse than none, so:

• Unknown is never reported as zero. A provider that cannot reach its source says so. "Unknown" and "0% used" produce opposite decisions.

• A degraded reading may only tighten a gate, never open one. Enforced mechanically, with a property test over the whole freshness ladder.

• Attribution admits what it guessed. The vendor gives one number per account; splitting it across projects is inference. Every ledger entry records its method, and SUM(pct_delta) always equals the observed delta exactly — we may be wrong about who spent it, never about how much.

• A rollover is detected, never assumed. A bare utilization drop with an unchanged reset instant is a bad reading, not a fresh window — treating it as one discards a week of attribution and opens every gate on the account.

These are stated as executable rules in docs/05-invariants.md and tested in test/.

Where it came from

Overton is the quota half of Loopdeck2, extracted and rewritten. Loopdeck2 tried to be a whole control plane — workflows, GitHub, dispatch, a deck — and the ecosystem shipped better versions of all of it during 2026. What nobody shipped, across ~200 orchestrators surveyed, was allocating a share of a rolling subscription window to a project and enforcing it. Paperclip has budgets in dollars; Quotio does per-account failover; LoopX gives per-goal hints; claudexor rotates between accounts on exhaustion. None of them keeps a per-(account, window, project) ledger.

So this is the part worth having, alone, small enough to adopt without adopting anything else.

The metering findings that make it possible — the Anthropic OAuth usage endpoint and its mandatory User-Agent, and the rate_limits block Codex writes into its rollout JSONL — are documented in docs/02-providers.md.

Docs

Roster — the other half

Overton answers may this project spend on this account right now? It does not answer who is this seat, and how do I run as it? — which credential directory, which plan, whether the seat is even signed in.

Roster answers that, and reads the same accounts: block out of this config. One registry, two readers; neither tool requires the other, which is the point — adopt the one you need.

$ roster ls                                    # who is available to play
$ roster run claude-personal -- claude -p "…"  # identity, no gate
$ overton run side claude-personal -- claude   # gate, then identity

Together they are Desk — in an orchestra, a desk is two players sharing one stand.

Status

v0.1 — working, and young. Metering, attribution, allocation, gating, claims, CLI, HTTP and MCP all run against real accounts. 79 tests.

A web deck ships with the daemon at http://127.0.0.1:7787 — accounts against the clock, and a slider per project for dividing each account's week, which shows what every other project's share becomes before anything is written.

Not yet: attribution for spend on a machine other than the arbiter's — remote mode gates correctly there, but the transcripts are not on the arbiter's disk, so that spend lands in @interactive. Nor more providers than the three here. Issues and PRs welcome — especially new providers.

License

MIT © Ignacio Freiberg