Segreant

Govern the spend. Not the developer.

The financial control layer for AI coding agents, running on your own machine. Your agents' spend is metered, capped before a loop runs away with it, checked against the provider's bill, assigned to the budget it belongs to, and traced to the work it produced. And every number tells you exactly how much it can be trusted.

local-first · zero runtime dependencies · 3,000+ tests · Node 24+ · free to use, including at work (BUSL-1.1)

---

The problem

Coding agents bill by the token, and they fail expensively. An agent stuck in a loop overnight doesn't raise an error; it sends an invoice. Your monitoring can't see it, because a $0.002 request and a $0.40 retry loop look identical when all you measure is latency and errors.

Then finance asks a simple question, "what is AI costing us, and is it worth it?", and every tool answers with one confident number. That number is usually an estimate dressed as a bill, or a bill with no owner, or a value figure nobody can defend.

Four numbers, never one

Segreant is built on a single refusal: it will not collapse four different questions into one number.

	The question	Where the answer comes from
Metered usage	What did the traffic use, at list price?	Segreant's proxy or your tools' own logs, priced from a versioned local rate card
Provider-billed cost	What did the provider actually charge?	The provider's cost export or Costs API (OpenAI today), imported and kept separate
Allocated cost	Whose budget does it belong to?	Allocation rules you write, reported together with what they left unallocated
Value	Did the spend become shipped, kept work?	Outcome evidence from git, tests and your reports

Every figure on every screen says which of the four it is. When the evidence for a number is missing, Segreant shows unknown. It never fills in a guess.

What makes it different

Most cost tools are dashboards. Segreant is an accounting system with an evidence model underneath, and it behaves like one.

• Every row carries its provenance. Each priced request records the exact rate-card SHA-256 and whether the price was an exact, family or fallback match. Repricing appends a before/after event; nothing is silently overwritten.
• Budgets fail closed. If the budget config is malformed or the ledger can't be read, Segreant stops forwarding. A broken meter never becomes an unlimited one.
• Reconciliation shows its residual. When metered spend and the provider's bill disagree, the gap is reported with the conditions that explain it and what it can and cannot bound. It is never forced to zero.
• Allocation conserves money. Allocated plus unallocated equals the ledger total to the microdollar, checked on every run. A run that doesn't balance is refused.
• Model comparisons know when they're confounded. Cheaper-model trials use anytime-valid intervals, correct for multiple comparisons, and flag themselves when the work sizes differ, the sample spans a price change, or the commits came from too few sessions.
• Evidence you can hand to someone else. Realized work produces ed25519-signed value receipts. The whole evidence ledger exports as a .segreantpack that a standalone verifier checks offline, without trusting Segreant.
• A kernel that can't be talked into certainty. Claims live in a small trusted core that tracks four evidence states: unknown, supported, refuted and conflicted. It refuses derivations that would strengthen a claim beyond its evidence, and revoking a source revokes everything built on it.
• Zero runtime dependencies. Node's built-in SQLite and nothing else. CI proves it with a CycloneDX SBOM on every build.

See it in 30 seconds

No API key, no account, no setup. With Node 24 or newer:

npx segreant demo --serve   # labelled synthetic data; opens the dashboard

Open http://localhost:8091. You'll see a month's statement with all four figures, spend by project and model with each session and what its commits came to, caps and alerts, a comparison with a generated provider bill, cost-centre splits, and what the spend produced, with a review-only cheaper-model comparison. It all runs on an isolated demo.db and is labelled as synthetic. Clear it with segreant demo --clear.

Use it on your real work

Install the segreant command (it has no runtime dependencies):

npm install -g segreant

On Windows, a project-local install (npm install segreant) inside a folder whose path contains & cannot start through npx or node_modules\.bin: npm's generated .cmd shim does not quote that path. The global install above and npx segreant from any folder are not affected. For a local install there, run node node_modules/segreant/bin/segreant.mjs instead.

Option A: no wiring at all. If you use Claude Code, Codex or opencode, Segreant reads the usage those tools already log on your machine, including subscription usage a proxy never sees. Antigravity is read too, from 0.2.0 on:

segreant scan            # finds your AI tools and git repos; changes nothing
segreant scan --setup    # imports that usage and groups it by project
segreant today           # what today cost, by model, project and tool

Option B: route traffic through Segreant to meter it live and enforce budgets:

segreant start         # proxy on :8090, dashboard on :8091

segreant launch -- claude     # or codex, opencode, aider, ...

launch points only that one tool at the proxy, and only while the proxy is running. If the proxy is stopped, the tool starts unmetered with a warning, or not at all when a budget cap is set. To point a shell at it yourself instead:

export ANTHROPIC_BASE_URL="http://localhost:8090"
export OPENAI_BASE_URL="http://localhost:8090/v1"

A tool pointed at the proxy this way cannot connect while Segreant is stopped.

Requests to OpenAI's and Anthropic's official APIs go through as soon as Segreant starts: that traffic was already going to your provider, and Segreant meters it on the way. Everything Segreant would send on its own (webhooks, team rollups, hosted judging) stays off until you allow it, and another provider or gateway needs one rule, which a refused request prints (GETTING-STARTED.md). Then set a cap:

segreant budget --daily 25 --soft 18 --runaway 2   # hard cap, warning, loop guard

Caps are opt-in. A fresh install meters but never blocks. Unset the two variables and Segreant is out of the path.

Per-tool recipes (Cursor, aider, opencode, Antigravity, your own SDK scripts): docs/INTEGRATIONS.md.

What you can do with it

• See the spend. By day, project, model, tool and developer, in the terminal (segreant today, week, month) or the dashboard. Export CSV for your own BI.
• Stop runaway agents. Daily, per-session and velocity caps on proxied traffic.
• Check against the real bill. Import an OpenAI cost export, or pull OpenAI's Costs API read-only, and reconcile it against what Segreant metered at project-day level. See PROVIDER-RECONCILIATION.md.
• Allocate to cost centres. Versioned, effective-dated rules, reported as showback. See ALLOCATION.md.
• Measure what the spend produced. Return on Intelligence follows each commit through tested, merged, shipped and survived. See RETURN-ON-INTELLIGENCE.md.
• Try a cheaper model, carefully. segreant frontier compares models on the same kind of task. It never changes your routing for you.
• Keep your data yours. SQLite on your disk, verified backup and restore, and evidence packs you can sign and verify.

In the dashboard, without the terminal

segreant start serves a local dashboard organised by job:

• Statement: one calendar month, side by side. What was measured, what the provider billed, how it was split, and what it produced. The four are never added together, and the month downloads as a CSV.

• Spend: where the measured spend went, by project, model and source.

• Protect: caps and alerts that stop spend before it happens.

• Close: declare the OpenAI project, bring in the cost export, and record the comparison with what Segreant measured.

• Allocate: cost centres, the rules that assign spend to them, and the monthly split, previewed before it is recorded.

• Value: what the spend produced, with the limits stated.

• Settings: choose what you see, from density to which jobs sit in the top bar, and a map of everything Segreant can do. Each capability the dashboard runs opens from that map in one click.

Splits, bill comparisons, imports, adoptions and budget changes show a preview before anything is saved. The dashboard follows your system's light or dark setting, works at phone width, and loads nothing from the internet.

Every command, flag and design detail is in the Segreant guide.

For teams and enterprises

The same local tool scales up without sending prompts or code to any Segreant-run service:

• Team rollups. Each machine signs and pushes per-project value and spend summaries to a team server you run. Per-developer views are opt-in, distribution-only and k-anonymous.
• Finance-ready output. Cost-centre allocation with conservation checks, provider-billed evidence with digests and coverage declarations, and a FOCUS-compatible billing export.
• Identity and storage. The team server supports OIDC sign-in and PostgreSQL.

The team server is implemented and tested, but it has not yet been validated in a production deployment; see team-server/README.md before exposing it to a network.

What Segreant will not claim

Built to be believed, so it is strict about what it says.

• A local estimate is not a bill. Metered amounts are list-price estimates. Provider figures are imported separately, and reconciled cost never feeds budgets or recommendations.
• Value is not causation. The dollar figure in the value view is an Observed value scenario: manual-equivalent value under assumptions you set. It is not a causal return. A causal net benefit result is separate and requires a registered randomized study (see CAUSAL-EVIDENCE-PROTOCOL.md).
• Attribution labels are declarations, not verified identity. Each label records how it was obtained, and a missing one stays missing.
• Not surveillance. Personal views are for self-improvement. Team views are opt-in and aggregate-only.

The complete, test-enforced list of what is supported, intended and not offered is CAPABILITY-EVIDENCE-CONTRACT.md.

Privacy

Segreant has no hosted service and sends no telemetry by default. The ledger lives under ~/.segreant, and the dashboard loads nothing from third parties: no CDNs, fonts or analytics. Requests you route through the proxy still go to the AI provider you configured, and your API keys pass through without being stored. Segreant also downloads the public price list when it meets a model its rate card does not know; that download sends nothing about you, and segreant pricing --auto off stops it. Every other outbound path (alert webhooks, team rollups) is opt-in. The privacy statement is PRIVACY.md, also one click from every dashboard page; every path in detail is in DATA-BOUNDARIES.md.

Status

Segreant is pre-release (0.1.0), published on npm as segreant. CI covers Linux, macOS and Windows, including a packaged-install smoke test, real-browser tests and supply-chain checks. Reconciliation and outcome measurement are implemented and tested but have not yet been validated against real provider accounts or with outside users. That is what the first users will prove.

If you try it, what confused you or what broke is the most useful thing you can send: open an issue or start a discussion.

Documentation

Start here	Go deeper	Trust and boundaries
Getting started	Segreant guide	Data boundaries
Integrations	Architecture	Capability contract
FAQ	Methodology (plain language)	Threat model

The full index is in docs/README.md.

By the numbers

Product code	~105,000 lines of strict TypeScript
Tests	~81,000 lines, 3,000+ test cases across the CLI, dashboard, team server and a real browser
Runtime dependencies	0
CI	14 checks on every pull request: three operating systems, install paths with spaces and &, the team server against real PostgreSQL, a packaged install, supply chain, real-browser tests, and exact-head verification

Development

npm install          # dev-only: typescript + @types/node
npm run build        # compile to dist/
npm test             # the full suite
npm run typecheck    # strict TypeScript
npm run demo         # rebuilds, then the demo dashboard from this checkout
npm run start        # rebuilds, then the proxy and dashboard from this checkout

See CONTRIBUTING.md for how changes are verified, GOVERNANCE.md for who decides what, SECURITY.md for reporting a vulnerability, docs/COMPATIBILITY.md for what stays stable, and docs/RELEASE-PROCESS.md for how a release is gated.

Supporting Segreant

Segreant is built independently and is free to use for everyone, people and organizations alike (LICENSING.md). Paying never unlocks features (docs/NEUTRALITY.md makes that a checkable commitment).

License

Business Source License 1.1 with an Additional Use Grant: anyone, person or company, may use, change and build on Segreant for free, including selling their own products built on it. The two things not allowed are offering Segreant as a hosted service and selling Segreant itself. Two years after each version is published, it becomes Apache 2.0 open source. Plain words: LICENSING.md.