Trazum
Documentation
The documents of the repository, readable here. Start with a task, or search the headings.
Start with a task
| Task | First page | Then |
|---|---|---|
| See a result in minutes | Quick start | Setup and integrations |
| Understand recorded spend | Usage logs | Commands, plans |
| Import Codex sessions | Codex sessions | Local rollout telemetry and its limits |
| Import Gemini CLI sessions | Gemini CLI sessions | Read from the recorder's own source; reasoning billed as output |
| Compare an agent task before and after a change | Task efficiency | Local dashboard workflow; CLI/MCP commands since 2.6.0 |
| Set a budget | CI gates | Gateway, scheduled checks |
| Build an integration | Agents and harnesses or Setup | Local HTTP API, JSON output, building on the JSON |
| Change Trazum | Contributing | Rules, releases |
Start here
A first result in minutes, and the setup behind it.
- OverviewOne command reads the sessions Claude Code, Codex and Gemini CLI already keep on your disk and prints the bill: by project, by model, by day. Then it ranks what to change and checks whether the…
- Quick startChoose recorded usage to understand spend, or a prompt to estimate an edit. You need Node.js 20 or newer. npx may download Trazum; the analysis below runs locally and requires no provider key.
- Setup and integrationsInstall only the interface you need. For a first result, start with the quick start. This page covers configuration and integration.
Using Trazum
Commands, formats and integrations, in the order you meet them.
- The command referenceStart with the quick start for a first result, or setup for installation and integrations. This page contains the detailed recipes and their limitations. trazum <command> --help lists flags.
- Codex sessionsImport a local Codex rollout to estimate its API-equivalent usage. This is not a subscription invoice or proof of the amount a provider charged.
- Gemini CLI sessionsImport local Gemini CLI sessions to estimate their API-equivalent usage. On the free tier or a Gemini Code Assist plan this is what the same work costs at Google's list prices, not what you paid…
- Usage logsRecorded spend comes from usage data. Prompt-only cost figures are projections. The prompt rules work without one — they count tokens — but "this label costs $340 a month and two thirds of it is the…
- AccountsSigning in is off by default. With nothing configured, Trazum's web app is what it has always been: you paste a prompt, it answers, and it remembers nothing about you. Nothing in this document is…
- Local HTTP APItrazum serve exposes read-only cost and savings analysis on 127.0.0.1, or a Unix socket. It estimates a proposed call against the configured budget and scoped limits. It does not invoke a model…
- Tool-output filtertrazum filter compacts consecutive identical lines in a display log before an agent reads it. It runs locally without a model or provider key. It keeps unique lines and diagnostic lines containing…
- Efficient context instructionsTrazum's plugin already gives an agent a skill and MCP tools for prompt checks, optimization, usage analysis and budget decisions. It does not intercept every host-model turn or control a…
- Task efficiencyAvailable in the dashboard and CLI/MCP 2.6.0 and later. This workflow groups explicitly supplied Claude Code and Codex transcripts under one task, finds repeated tool calls for review, and compares a…
- Agent integrationsTrazum separates the harness that executes an agent, the model/provider that serves requests, and the payment mode that determines the invoice. Use the same analysis and plan documents across…
- The gatewayThen point your SDK's base URL at what it prints and change nothing else. It speaks the provider's own wire format, so there is no new client, no wrapper and no code change.
- CI gatesTrazum is one binary with meaningful exit codes. That is the whole integration story, and it is deliberate: a tool that only gates on one vendor's CI is a tool half its readers cannot use, and every…
- Running it on a scheduleEverything in Trazum happens when somebody runs a command. The failures worth catching — a retry loop, a prompt that grew, a model swapped in a deploy — happen at 3pm on a Tuesday, and a report…
- Deploying on N0What ships is the web app (apps/web) and nothing else. The CLI, the gateway and trazum serve are loopback-only by design — a cost oracle on a network interface is an attack surface — and they belong…
- The plan documentplan.json is the one thing Trazum writes that is meant to be kept. Every other output answers a question the moment you ask it; a plan is a decision written down on Monday and checked on Friday, by a…
- JSON outputDocumentation / Command reference · Format contracts · Plan format
- Building on the JSONDocumentation / JSON output · Format contracts · Local HTTP API
- The interchange formatTrazum emits twenty-six documents as data, and it defines a twenty-seventh it does not emit. The task document is one versioned family with report, comparison and policy-receipt variants. This index…
- The pricing datasetTrazum's price catalogue, packages/core/src/pricing.ts, published as JSON with every release, for anybody who wants the prices without the tool: one row per model and rate, each with its provider…
Deciding whether to use it
Why the numbers deserve trust, and what the project says about itself.
- The doctrineEvery rule below was discovered by getting it wrong first. They are written down together here because they are the actual argument for why anybody should trust a cost figure — from this tool or any…
- Our own medicineThis project gates other people's promises, refuses to let them merge a measured figure with an estimated one, and insists that a plan which did not arrive says so out loud.
- Any inputThis page states what Trazum promises about input it was never meant to see — and where each promise is enforced, so the claim can be checked rather than believed. It exists because a stress session…
- When a change is doneA change here is done when every check that can be run before the push has been run and passed, and what was planted to prove each new guard is written down. Not when the code looks right, and not…
- CoverageWhich lines of the published packages the tests run. npm run coverage measures it, the Coverage workflow sends it to Codecov on every pull request and on main, and Codecov shows it line by line.
- End-to-end testsThe web app's other tests read modules and rendered components. These open the page in a real browser, against the production build, and do what a visitor does: paste a log and read the bill…
- Mutation testingA passing test suite says the code does what the tests ask. It does not say the tests ask enough. Mutation testing asks the second question, mechanically: change one small thing in the code, run the…
- What is open, what is notIf you are deciding whether to build on this, the licence file answers one question and leaves three unanswered. This page answers the other three: what the licence covers today, what could plausibly…
Extending it
Writing a rule, a dictionary or a change.
- Authoring rulesA rule removes or rewrites something in a prompt that costs tokens without earning them. This is everything you need to add one without reading the engine — which is the point: the engine's job is to…
- Maintaining a languageTrazum's trimming dictionaries cover seven languages. Two of them have somebody here who reads them. Five do not.
- The prompt writerThe first chapter of the 1.61 arc. trazum write starts from nothing and asks; what it asks is the product.
- ContributingTwo things before the detail. CODE_OF_CONDUCT.md applies to everyone taking part here, maintainer included, and it is explicit about what a single-maintainer project can and cannot promise about…
Maintaining it
Direction, versions and releases.
- FinOps product directionDirection: position Trazum around the cost and capacity needed to complete useful work, then use measurements to improve the next task. The task efficiency workflow is implemented in the 2.6.0…
- Adoption playbookThis is a proposed 30-day experiment, not evidence of traction or a growth forecast. Start day 1 when a maintainer begins recruiting. Keep participant identities, contact details and raw interview…
- ReleasingPublishing is the one action in this repository that cannot be undone. npm allows unpublishing for 72 hours and then the version number is spent for good — it can never be reused, even for identical…
- VersioningTrazum follows semantic versioning for the thing semver exists to protect — breaking changes — and uses the minor and patch fields to carry the release narrative. Both halves are stated plainly below…
Also on the site
Three questions asked before trusting a tool that prints a bill, answered from the repository’s own files.
Kept in the repository
These are records, not instructions. They stay on GitHub, and nothing on this site rewrites them.