README
¶
costcrew - FinOps, staffed by agents
A crew of agents takes your bill apart. A person stamps every line before it counts.
costcrew is a FinOps console in which a crew of agents does the analysis and a person reviews it. Analysts are hired into desks with a mission, an owner, rights that follow from their skills and a monthly guard. They triage anomalies, write variance commentary, propose rightsizing, draft explainers and freeze forecasts. Every deliverable arrives as a draft, and only a person's stamp publishes it.
One static binary over pure-Go SQLite. No interpreter, no second database engine in the process, and zero JavaScript in the web UI.
The same service as its room on it-rat.com draws it, where twelve frames of the running console sit beside this.
Where this fits in the stack
CostCrew is the finops plane: it reads the bills the other planes never see, and it is the one plane in the stack that deliberately cannot stop anything.
flowchart TB
Agent["AI agent (any framework)"] -->|"LLM call (base-URL swap)"| TF["TokenFuse proxy: spend + enforcement"]
TF -->|"POST /v1/decide (PEP)"| WX["Wardryx: policy PDP"]
WX -.->|"allow / deny / hold"| TF
TF -->|"cheapest model, budget OK"| LLM[("LLM provider")]
TF -->|"CallRecords"| CL["TokenFuse Cloud: control plane, incidents, replay, evidence, kill-switch"]
VCX["Vouchryx: delegation proved, and endable"] -->|"short-lived token: act + cnf"| TF
TF -.->|"polls /v1/revocations"| VCX
VCX ==>|"delegation_issued / denied / revoked"| BUS
TF ==>|"agent-event NDJSON"| BUS{{"agent-event bus + Agent Passport"}}
WX ==> BUS
Agent -->|"web fetch"| SCX["Scopyx: governed web egress"]
SCX -->|"POST /v1/decide"| WX
SCX ==>|"web_fetch / web_blocked"| BUS
ENG["Engram: memory"] -->|"reflect via base_url"| TF
ENG ==> BUS
BUS ==> IDX["Idryx: identity graph, detectors, Agent-BOM"]
IDX ==>|"identity_finding"| BUS
BUS ==> QX["Qryx: crypto / PQC, passport + hash-chain scan"]
QX ==>|"crypto events"| BUS
BUS ==> VX["Verdryx: quality / drift"]
VX ==>|"quality events"| BUS
TF -->|"outcome-tagged traces"| VX
MX["Mockryx: pre-prod safety rehearsal"] -->|"hostile scenarios"| TF
MX ==>|"sim events"| BUS
BILL[("cloud, SaaS and model bills")] --> CC["CostCrew: the bill, worked by a crew of agents"]
CC ==>|"spend_spike / budget_threshold / crew moves"| BUS
BUS ==> TRX["Trailryx: the record plane, sealed and packed"]
BUS ==> HX["reads the log, mails you (heraldyx)"]
HX -->|"one mail, a view and never an action"| OPS["your mailbox"]
HX ==>|"alert_sent"| HJ[("heraldyx's own hash-chained journal, not this bus")]
YOU(["you, in a browser over your own tunnel"]) --> GX[["Genaryx: the console over all of it"]]
GX -->|"signed commands: the kill, an approval, a policy"| CL
GX -->|"signed commands"| WX
GX ==>|"console_command"| BUS
GX -.->|"reads it"| IDX
GX -.->|"reads it"| QX
GX -.->|"reads it"| VX
GX -.->|"reads it"| MX
GX -.->|"reads it"| ENG
GX -.->|"reads it"| SCX
GX -.->|"reads it"| CC
TFP["terraform-provider-taipan"] -->|"budgets + passports as code"| CL
ASG[["agent-stack-go: shared Go contract"]] -.->|imported by| IDX
ASG -.->|imported by| WX
ASG -.->|imported by| MX
ASG -.->|imported by| TFP
ASG -.->|imported by| HX
ASG -.->|imported by| QX
SPEC[["agent-passport: the spec"]] -.->|governs| BUS
- Consumes: billing exports and vendor usage APIs, never another service's store. Ten connectors: AWS Data Exports (FOCUS 1.2), Cost Explorer, GCP BigQuery billing export, Azure Cost Management, Kubecost, OpenCost, Anthropic and OpenRouter usage, Compute Optimizer, SaaS seats. Seven built, three documented, and every entry declares whether running it is metered per call.
- Produces: fifteen event types on the shared agent-event bus, registered in
agent-passportSPEC 6.2 under the sourcecostcrew, schema v0.2. - Enforces: nothing.
enforced: falseis stamped on every event, the console makes no outbound call while serving a page, andinternal/enforceis a separate binary it never imports.
The three rules that make the numbers usable
It enforces nothing, by design. An analyst that executes its own conclusions is no longer an analyst. Stopping a runaway is TokenFuse's job, ending an authority is Vouchryx's, and the console over both is Genaryx.
Money is found, never saved. Nothing is saved until somebody acts and the invoice changes. The seeded estate is blunt about what that means: the crew has found 1,254.35 and cost 3,871.35 across 310 tasks, and the Results page prints the ratio without softening it.
A measure may refuse. The KPI library reports nine numbers and refuses three, each refusal naming what is missing. A library where everything reports a number is one where several of them are invented. The refusal it will not talk around is per-agent AI spend: a charge carries a model and a workload, never an agent, and that becomes answerable only when the calls go through TokenFuse with an agent id.
The detector
A median with a robust deviation rather than a mean, so last month's spike does not raise the bar for this month. Two-sided, because a feed that stopped delivering and a workload switched off unnoticed both look exactly like a drop. A Sunday is judged against Sundays. And findings are ranked by money, because a four sigma deviation worth three dollars is real, true, and not worth anybody's morning.
Run it
go install github.com/TAIPANBOX/costcrew/cmd/costcrew@latest
costcrew -data ./local
It listens on 127.0.0.1:8321 and expects a proxy in front of it for TLS. The
first account created at /signup becomes the admin of that installation, so
make one before you hand anybody the address.
Inside the stack, ./up.sh --with-finops from
stack-up brings it up wired to the
shared bus. Two flags carry the whole integration: -stack-events names the
NDJSON file, and the name IS the integration because genaryx keys a read offset
off the stem; -stack-host sets the agent:// authority.
Gates
go test ./... # 261 tests, 16 packages
./scripts/features-are-bound.sh # every scenario bound to a named test, both ways
./scripts/gates-have-teeth.sh # 45 cases: each gate is made to fail on purpose
gofmt -l . && go vet ./...
The teeth harness is the one worth knowing about. It plants each gate's own fault and requires the failure, requires the gate NOT to fire on a non-fault, and requires it to say it measured nothing rather than reporting OK when its subject has been taken away.
Status
- Rewritten in Go, the Python original deleted 2026-08-25
- Registered producer on the shared bus, fifteen types in SPEC 6.2
- Installed by
stack-up --with-finops - Live agents:
tools/run -liveprices the worst case before every call - Per-agent attribution of AI spend, which needs TokenFuse in the path
- A console route that starts a crew run; today that is a CLI
Licence
Apache-2.0, like the rest of the stack. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
costcrew
command
Command costcrew serves the FinOps analyst console.
|
Command costcrew serves the FinOps analyst console. |
|
internal
|
|
|
anomaly
Package anomaly turns a detection into something with a life.
|
Package anomaly turns a detection into something with a life. |
|
auth
Package auth is accounts, sessions, roles and the demo guard.
|
Package auth is accounts, sessions, roles and the demo guard. |
|
connectors
Package connectors is the catalogue of places the estate's numbers can come from, and what it costs to ask.
|
Package connectors is the catalogue of places the estate's numbers can come from, and what it costs to ask. |
|
crew
Package crew is the work: sprints, the tasks in them, the deliverables analysts write, and the operator's stamp that makes one count.
|
Package crew is the work: sprints, the tasks in them, the deliverables analysts write, and the operator's stamp that makes one count. |
|
detect
Package detect finds irregularities in a daily cost series.
|
Package detect finds irregularities in a daily cost series. |
|
enforce
Package enforce pushes this console's budgets to the thing that can stop a call: TokenFuse's control plane.
|
Package enforce pushes this console's budgets to the thing that can stop a call: TokenFuse's control plane. |
|
engines
Package engines is where the crew's model calls come from.
|
Package engines is where the crew's model calls come from. |
|
finops
Package finops is the money work: giving shared cost an owner, closing a period so the numbers stop moving, and saying what the crew found.
|
Package finops is the money work: giving shared cost an owner, closing a period so the numbers stop moving, and saying what the crew found. |
|
history
Package history gives a fresh installation a past.
|
Package history gives a fresh installation a past. |
|
money
Package money carries amounts as integer cents.
|
Package money carries amounts as integer cents. |
|
pyrand
Package pyrand reproduces Python's random.Random bit for bit.
|
Package pyrand reproduces Python's random.Random bit for bit. |
|
spiffe
Package spiffe holds the identity this console was ISSUED, if it was issued one.
|
Package spiffe holds the identity this console was ISSUED, if it was issued one. |
|
stack
Package stack puts CostCrew on the agent-governance stack directly.
|
Package stack puts CostCrew on the agent-governance stack directly. |
|
store
Package store owns the console's own state: accounts, sessions, the board, and the hash-chained journal.
|
Package store owns the console's own state: accounts, sessions, the board, and the hash-chained journal. |
|
web
Package web serves the console.
|
Package web serves the console. |
|
world
Package world defines the estate the console opens onto: the teams that spend, the desks that watch them, the analysts hired to each desk, and the events planted in the cost series.
|
Package world defines the estate the console opens onto: the teams that spend, the desks that watch them, the analysts hired to each desk, and the events planted in the cost series. |
|
tools
|
|
|
enforce
command
Command enforce shows what this console's budgets would set on TokenFuse's control plane, and sets them only when told to.
|
Command enforce shows what this console's budgets would set on TokenFuse's control plane, and sets them only when told to. |
|
idryxsource
command
Command idryxsource writes this console's roster as an idryx `agents` source, so the identity graph can carry the agents this console hires.
|
Command idryxsource writes this console's roster as an idryx `agents` source, so the identity graph can carry the agents this console hires. |
|
parity
command
Command parity captures and compares the observable surface of a CostCrew installation, so a Go implementation can be held against the Python one.
|
Command parity captures and compares the observable surface of a CostCrew installation, so a Go implementation can be held against the Python one. |
|
recon
command
Command recon prints the console's planes against the ledger they are derived from.
|
Command recon prints the console's planes against the ledger they are derived from. |
|
run
command
Command run says what it would cost to let the crew actually write, and does not let it.
|
Command run says what it would cost to let the crew actually write, and does not let it. |
|
stack
command
Command stack connects an existing CostCrew crew to the TAIPANBOX agent-governance stack, one analyst at a time or a whole desk at once.
|
Command stack connects an existing CostCrew crew to the TAIPANBOX agent-governance stack, one analyst at a time or a whole desk at once. |