Skip to content
Trazum

Quick start

Documentation / Quick start

Choose 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.

1. Get a first result#

Already using Claude Code, Codex or Gemini CLI?

npx @trazum/cli bill

This reads their local sessions, names each folder before reading it, and splits the cost by agent, project and model. Add --by week (or day, month) for a table by period. The amount is API-equivalent cost, not your subscription invoice. Unknown models remain named pricing gaps.

Have an export instead?

npx @trazum/cli bill ./usage-export.jsonl

Use your own path. bill detects supported provider and observability export shapes. Supported inputs and required fields.

For a reproducible demo from a clone of this repository:

npm install
npm run build
node packages/cli/dist/index.js bill examples/claude-projects

These are illustrative fixtures, not a customer's spend. The report groups priced calls by project and model and names missing information.

2. Export the evidence#

npx @trazum/cli bill ./usage-export.jsonl --html-out bill.html

HTML carries the report and its caveats. PDF, CSV and Markdown exports are also available. Treat reports as financial information when sharing them. For normalized logs, profile exposes deeper analysis:

npx @trazum/cli profile ./usage.jsonl

Import a usage log before passing provider-specific exports to profile. Bill and profile reference.

3. Save a plan for one change#

For a normalized usage log (use your own path):

npx @trazum/cli plan ./usage.jsonl -o plan.json

If you started with agent sessions, convert them first. Claude Code is shown; Codex and Gemini CLI have from-codex and from-gemini-cli:

npx @trazum/cli from-claude-code ~/.claude/projects --label-from-project -o usage.jsonl
npx @trazum/cli plan usage.jsonl -o plan.json

Other exports need their corresponding usage importer. bill accepts more input shapes than plan; do not pass an arbitrary provider export directly to plan.

Read the top action, its assumptions and the period it covers. Choose one change you control. Check quality on representative tasks before changing a model or prompt, and check whether your workload tolerates batch latency. A plan with no actions is valid; do not manufacture savings to fill it.

On a fixed subscription, a lower API-equivalent estimate does not imply a lower subscription payment. This workflow is most directly useful when you pay for the affected API usage.

4. Check later usage#

After applying a change, collect a new normalized log for the same workload, keeping workload labels consistent. Use a separate file for the later period, not a second export containing all the original history.

npx @trazum/cli verify plan.json --against ./usage-after.jsonl

Expect one of three outcomes: savings arrived, did not arrive, or cannot be determined. Read the explanation alongside the verdict: traffic, pricing and missing fields can affect the comparison. This does not establish causality, prove unchanged answer quality, or reconcile your provider invoice. Plan format and verification limits.

Subscription efficiency#

For a fixed subscription, focus on useful work per task and context quality, not projected invoice savings. With a normalized log carrying consistent session identifiers, profile can describe conversation growth:

npx @trazum/cli profile ./usage.jsonl

Growth is not all waste: later turns may need earlier decisions, new files or new user requirements. Treat the report as a reason to inspect the workflow, not permission to remove context indiscriminately.

For a prompt or instruction file you control, inspect a proposed edit:

npx @trazum/cli optimize ./prompt.txt --diff

Review changes and compare representative tasks before adopting them. Record input/output tokens per completed task where available, retries, and quality. A shorter prompt that causes more retries may be worse overall.

You can also enforce a chosen token budget on that file:

npx @trazum/cli check ./prompt.txt --max-tokens 2000

Here 2,000 is an example policy, not a provider limit or a recommended budget for every task. These checks do not control the agent's complete context, compact its conversation, or translate tokens into remaining subscription messages. Selecting relevant files and starting a new session with a carefully reviewed handoff summary remain host/user workflow decisions.

For an optional agent instruction template and its limits, see efficient context instructions.

Other workflows#

Your questionNext step
Can this prompt fit a budget?CLI setup, then CI gates
Should I configure this repository?Optional project setup with init
Can calls be refused before forwarding?Gateway setup and limits
Can my agent use it?MCP or Claude Code plugin
Can I automate reporting?Schedules, watch and alerts

For a prompt without usage data:

npx @trazum/cli optimize ./prompt.txt --cost

Read the diff and assumptions. Projected savings do not prove unchanged answer quality; model recommendations require your own evaluations.

If the result is incomplete#

SymptomWhat to check
No usage foundPass an explicit file or folder; see input formats.
A model cannot be pricedInspect trazum models; use a pricing overlay backed by your rate card.
The cost differs from an invoiceCheck period, credits, subscription pricing, missing calls and provider rates. See reconcile in the reference.
A finding is unavailableSupply the missing fields; missing evidence is not zero spend.
A command failsRun trazum <command> --help; use support with a redacted reproduction.

Local analysis does not upload your files. Optional provider calls and saved web-library prompts have different data paths: read privacy and accounts before enabling those integrations.