Trazum

Trazum

Understand your AI spend. Decide what to change.

Find where your AI usage costs money, choose a change, and check the result. Trazum analyses local usage logs and prompts, ranks opportunities such as caching and model changes, and keeps estimates separate from measured outcomes.

Open source · Local analysis · No provider key needed to get started

Start here: one command, no global install

Requires Node.js 20 or newer. npx may download Trazum from npm.

npx @trazum/cli bill

Illustrative data from examples/claude-projects, not a customer result. Generated from the CLI output.

With no path, bill reads local Claude Code transcripts and groups the result by project and model. On a subscription, this is API-equivalent cost, not what you paid. Unpriced models are reported as gaps. Local analysis does not upload your files.

Have a supported usage export instead? Pass its path:

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

Supported inputs · Try sample data in your browser

Turn a report into a decision

For teams paying for API usage, the useful question is what to change next. Start with your largest workload, review the assumptions behind one finding, and evaluate quality before changing models or prompts.

1. Understand usage: bill shows the recorded cost and coverage gaps.
2. Choose one change: plan ranks opportunities from a normalized usage log.
3. Check the outcome: verify compares the saved plan with later usage, including cases where the evidence cannot settle the result.

Follow the first-report-to-verification walkthrough. A projected saving is not a guaranteed reduction in your invoice.

Using a subscription?

A smaller API-equivalent estimate does not reduce a fixed subscription fee. Use Trazum to inspect conversation growth, review redundant prompt text and set token budgets for instructions you control. Check task quality before keeping a shorter prompt. This does not automatically manage your agent's context or guarantee more messages under your provider's limits.

Subscription efficiency workflow.

In the Tasks dashboard and CLI/MCP 2.6.0: task efficiency connects Claude Code/Codex task usage, repeated-tool evidence, a reversible instruction policy and an explicit acceptance decision. Compare observed usage before and after a change without inferring success or guaranteed savings.

Keep or share a report

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

PDF, CSV and Markdown exports are also available. Review the report before sharing it: it contains usage and cost information.

Pick your integration

Claude Code is the first native integration, not a provider lock-in. Codex session imports, normalized usage logs and provider exports feed the same core. MCP clients can query Trazum without having a native transcript adapter.

Harness, model and payment mode are separate facts. An API-equivalent estimate is not a subscription invoice; a model without a price remains a gap.

Your agents spend money in a loop. This prices the call before it happens.

One agent costs what it costs. A fleet of them spends in a loop nobody is watching per iteration, and the bill arrives a month later as one number with no per-decision detail inside it.

Trazum installs into that loop. The MCP server's first tool is spend_guard, and it is the only one here whose trigger is not a sentence somebody types:

"May I spend this?"  ->  yes, no, or cannot-tell.

A refusal carries the cheaper ways to make the same call, each priced for that call and each naming what it assumes. The ceilings come from your trazum.config.json; the spend so far comes from the usage log your host already writes. Nothing is called and nothing is spent to answer.

claude plugin marketplace add Davmunrey/Trazum
claude plugin install trazum@trazum

That one line brings the skill and the MCP server. An agent that reads Agent Skills from the repository instead gets the same skill with npx skills add Davmunrey/Trazum. Every other MCP client reads the same mcpServers JSON, so Cursor (.cursor/mcp.json), Windsurf, Claude Desktop and the rest are one paste:

{ "mcpServers": { "trazum": { "command": "npx", "args": ["-y", "@trazum/mcp"] } } }

The server is listed on the official MCP registry as io.github.Davmunrey/trazum, and every release updates the listing.

Or run it right now, without installing anything: the Playground

That link opens the CLI's pure subset running in the page, against sample files already loaded, through the same @trazum/core functions the terminal runs. Nothing you paste leaves your browser.

The argument, in one screenshot

Real output, transcribed. Read the last two lines: the rules recovered $24.00 a month, and the advisory above them is worth $528.40, 22 times more. That gap is the entire argument for this tool.

Generated by npm run draw:architecture, not drawn. architecture-image.test.js fails the build if a package exists that the picture does not show, if the core takes a dependency while the picture says it has none, or if a third module is allowed to reach a network without the picture saying so.

The prompt is the part everyone looks at, and usually the cheap part. In the run above, forty percent of the text came out and it moved 3.5% of the bill. What moved the rest was a question nobody was asking: does this task need the model it is running on?

Every figure has a receipt. Sixteen advisories, each priced per month and reproducible on a single file: caching you are not getting, work that could go through the Batch API, a schema costing tokens on every call to describe a shape the request could carry as a parameter. Underneath them, twelve deterministic rules that shorten the text itself: same input, same output, free, offline, and never touching code, URLs, email addresses or placeholders. On top, an optional LLM pass for the compression rules cannot do, through whichever provider you configure, which never runs unless you ask.

                      ┌──────────────┐
                      │ @trazum/core │   the library: rules, tokens, pricing
                      └──────┬───────┘   zero dependencies, browser-safe
    ┌────────────┬─────────────┼─────────────┬─────────────┐
 @trazum/cli  @trazum/mcp  trazum-vscode  @trazum/web    action/
 54 commands   MCP server    the editor      Next.js    comments on
              for your agents  status bar               pull requests

              @trazum/tokenizer-openai   optional: exact counts for OpenAI
                    install it or do not, nothing else changes

Contents

Limitations · Privacy · Pricing · Contributing

What it actually does

The analyser reports sixteen findings, with assumptions attached to each estimate.

1. Tells you where the money actually is. This is the part worth reading first, because it is where the numbers are. Every advisory is priced per month against your own call volume, and none of them is about making the text shorter:

The last four are advisory only. A contradiction has a right answer that only the author knows, and an example that looks redundant may be demonstrating a boundary case on purpose. Trazum points; it does not cut.

Structured output is a code change

Trazum can identify an output schema described inside a prompt and suggest using the provider's structured-output API instead. It never removes that schema automatically: the calling application must preserve the contract.

A constrained decoder can improve format reliability where supported. Moving a schema to a request parameter does not prove a billing saving: providers may still count schema tokens. Compare actual usage before claiming savings. The finding estimates the prompt text involved, not a guaranteed reduction in the provider's bill.

Only blocks preceded by an explicit output cue are considered. Example input is data the model may need and must not be removed as though it were a schema.

The example detector finds near-copies — the way few-shot blocks actually grow. It deliberately does not flag paraphrases: that case needs a model, and is on the roadmap for the LLM pass.

2. Then it trims the prompt itself. Twelve deterministic rules: courtesy, filler, verbose phrasing, duplicated paragraphs, decorative separators, shouting in capitals. Two levels — safe (no semantic risk) and aggressive (read the diff). This is the smallest number on the page more often than not, and it is reported that way rather than dressed up.

3. And never touches what would break the prompt. Code fences, indented code blocks, inline code, URLs, email addresses, template placeholders ({{x}}, ${x}, {x}, {% %}) and XML/HTML tags are isolated before any rule runs. If a rule ever did make one of those disappear, that rule is discarded and the rest carry on.

Reviewing an aggressive run. Every rule reports what it actually changed, so the level that saves the most is judged rule by rule rather than as one wall of diff — and a single rule you disagree with comes off with --disable:

  [aggressive] Intensifiers (3×, ~6 tokens)
      VERY → —
      extremely → —
      quite → —
  [aggressive] Self-verification instructions (1×, ~17 tokens)
      You should double-check your answer before re… → —

4. Optionally, runs it past an LLM. The result is only accepted if it is shorter and leaves protected content byte-identical. Otherwise the deterministic version stands. It never returns something worse than where it started. With --suggest it proposes phrases one at a time — You should always make sure to → Always — each checked against your prompt before you see it, so eight surviving out of ten is a useful morning rather than a rewrite to read end to end.

5. Answers the questions that come before "shorten this". Trimming one file is the smallest thing here. optimize is one of 54 commands — the table above names what each answers — because knowing a prompt is wasteful is not the same as knowing which prompt, whose change made it so, or whether the shorter version still works.

check, diff, rank and blame all take --markdown-out, so the answer can land in a pull request comment rather than a terminal nobody is looking at.

It gates in whatever CI you already run. One binary, two exit codes, and worked recipes for GitLab CI, Jenkins, CircleCI and a pre-commit hook — no vendor plugin, because each one would be a second code path that drifts from the exit codes it is supposed to relay.

The 54 commands

Getting started

Node.js 20 or newer. npx can download the package; local analysis requires no API key. Choose the task that matches the data you already have:

npx @trazum/cli bill ./usage-export.jsonl
npx @trazum/cli optimize ./prompt.txt --cost

The first reads recorded usage. The second estimates changes to a prompt; its projected savings are not a provider invoice. See the quick start for a reproducible example and next steps.

The first five minutes: trazum init

After your first report, optionally run npx @trazum/cli init in your project to inspect prompts and available usage, write a config and identify a finding. Read what init writes and refuses to overwrite.

CLI

Install with npm install -g @trazum/cli, or keep using npx. CLI examples and configuration cover token budgets, reports, CI and pricing overrides. Command reference.

The rest of the commands, in their own book

Find a command by task. trazum --help lists commands; trazum <command> --help explains its flags.

Web

Open the Playground to try sample files. For local development, run npm install, npm run build, then npm run dev:web. Web setup and API recipes.

Signing in (optional)

Accounts are disabled by default. Enabling them adds a saved prompt library and share links backed by the deployment operator's database. Account setup and data handling.

Deploying to Vercel

Deployment instructions, environment variables, and N0 deployment.

Library

Install @trazum/core to use analysis in your application. Library examples and package API.

Languages

Reports are available in English and Spanish (--locale es, or the browser's language on the web). A locale changes the report, never the optimisation: same optimised text, same token counts, same advisory ids in either language. The full story — what is translated, what is deliberately not, and how the report and the prompt each pick their language — is in the command reference.

Connecting your own LLM

The optional LLM pass (--suggest, eval, route) speaks to whichever OpenAI-compatible or native endpoint you configure by environment — vLLM, Ollama, OpenRouter, Anthropic, Gemini, Bedrock and Vertex included, keys never stored. Configuration, refusals and the --pricing-live overlay are in the command reference.

Every model you pay for by the token

Trazum prices Anthropic, OpenAI, Google, Moonshot, DeepSeek, xAI and Mistral:

Every report says how old the prices are — the date the table was checked and how many days ago that was — because every dollar figure descends from that list, and a date on its own makes you subtract against today to learn whether to trust it. Past 45 days the report says so in a sentence, rather than leaving the reader to decide what "old" means.

The 7 providers publish independently, so each carries its own review date and trazum models prints them; the headline figure above is the oldest of the seven, because the question "how old is this table" is about its worst part.

trazum optimize prompt.txt --model gpt-5 --calls 50000
trazum optimize prompt.txt --model kimi-k3
trazum models                      # the whole table, with each provider's terms

Everything that reads the prompt is provider-agnostic already — the rules, the protection pass, --reorder, the contradiction and example detectors all operate on text. What differs is the money, and that is not one set of numbers:

The cache minimum is the row to read twice, and it used to be wrong here. This table said "512 on Anthropic" flatly. Anthropic's floor is a property of the model: 512 on Fable 5.1, Fable 5, Mythos 5.1, Mythos 5, Opus 5.5, Opus 5, Sonnet 5.5 and Haiku 5.5; 1,024 on Opus 4.8, Sonnet 5 and Sonnet 4.6; 2,048 on Opus 4.7; 4,096 on Opus 4.6, Opus 4.5 and Haiku 4.5. A reader on Haiku 4.5 who trusted "512" would have built a prefix eight times too short and been told caching would save money that could never arrive — the one direction this tool must never be wrong in. trazum models prints the real figure per model, and every cache advisory has always used it; only this table was wrong.

Those last two rows are why the multipliers had to move onto the model. As global constants they offered a batch discount to providers that do not sell one and a caching saving to a model that has no cache — invented savings, which is the one thing this tool must not print. A provider with no batch API now gets no batch advisory, and no discount even if you tick the box: batchEligible describes the work, not what the provider sells.

A cheaper model means a cheaper model, not a different supplier. The downgrade advisory only ever suggests models from the provider you are already on. Dropping a tier is a one-line change; switching vendor is a migration, and this advisory is a keyword heuristic — it has no business recommending that you change supplier.

Not covered: subscription invoices. API token prices cannot establish how much a subscription bill will change. Claude Code, Codex and Cursor identify the tool, not its payment mode; Trazum defaults to token figures in those hosts. An explicit --cost requests an API-price scenario, not guaranteed invoice savings.

Optimising a prompt that lives in code

trazum optimize src/prompts.ts --prompt support --diff

It reads the marked prompt and leaves the file alone. Pointed at an unmarked source file it refuses, because optimising TypeScript as if it were prose does not produce a worse prompt — it produces broken code, and -o would write that back over your file. When a file holds several marked prompts it asks which one rather than taking the first.

The model comes from the code too, so a file calling OpenAI is priced against OpenAI. --model and trazum.config.json still win: flags beat config, config beats detection, detection beats a built-in default that has no idea which provider you use.

Which provider is this prompt even going to?

Since Trazum prices 7 providers, defaulting to Claude became a wrong number: a file calling OpenAI was billed against Claude Opus 5 without comment. trazum where reads what the code already says.

trazum where src/prompts.ts

Running inside
  Claude Code (CLAUDECODE)
  Claude Code identifies the execution host only. Payment mode is unknown;
  token prices do not establish invoice savings.

Prompts in src/prompts.ts go to
  anthropic · Claude Sonnet 5
    line 2  model-literal: claude-sonnet-5
    line 1  sdk-import: @anthropic-ai/sdk

Priced as
  Claude Sonnet 5 (read from the source)

Every answer names the line it came from. Four kinds of evidence, strongest first: model= on a trazum:prompt marker, a quoted model id, a base URL, an SDK import — and a base URL beats the SDK it was pointed at, because Moonshot, DeepSeek, xAI and Groq are all called through the OpenAI SDK with a different base_url. It refuses when a file names two providers: picking silently is how somebody budgets against the wrong provider for a month. Detection sits in the usual layering — a flag beats config, config beats detection, detection beats the built-in default.

With no file it reports only the host. Environment variables identify the tool, not whether a workload uses an API, a subscription, credits or a local model:

Agent harnesses default to tokens, not invoice savings

Inside Claude Code, Codex or Cursor, Trazum conservatively defaults to token figures. This is a display policy, not a claim about your payment arrangement. Use --cost to request the API-price scenario; it is not a subscription invoice:

What this buys on Claude Code
  Claude Code identifies the tool, not your payment mode. Tokens are shown
  by default; invoice savings are unknown.

  1,001 tokens back, every call.
  Context window: 12.4% → 2.1% of Claude Opus 5's 1,000,000 tokens — room the
  conversation gets instead.
  Pass --cost if this prompt is bound for a metered API.

The context window is the real currency in an agent: every token the system prompt holds is one the conversation cannot.

Advisories whose only pitch is money are hidden in this view. Whether they reduce your invoice depends on your payment arrangement. model-downgrade, batch-api, output-dominated and promo-pricing are dropped; caching, context overflow, contradictions and redundant examples stay, because latency, headroom and correctness are still real.

The escape hatch matters. The host says where Trazum runs, not where your prompt goes — somebody editing a production prompt inside Cursor wants the dollars, and --cost gives them back without leaving the editor. --tokens-only forces the other direction anywhere.

Where the money actually went: trazum profile

The command the rest of the product orbits: hand it a usage log (or a directory of rotated ones) and it reads what the provider actually charged — the spend split, whether caching paid for itself, conversation growth, the answers cut off mid-generation, and the levers that would genuinely move the bill, priced from your own calls. It reads counts, never content; a session key groups and is never printed; a model it cannot price is named and kept out of the totals rather than silently absorbed.

The full chapter — the record format, --against, --what-if, the cache post-mortem, the conversation ceiling, every gate — is in the command reference.

Where this fits, said at the front door

Every optimize run closes with the same sentence, because it is the truth about what the command just did:

  Shortening a prompt is the smallest lever there is: measured on an ordinary
  support prompt, the rules recover about 1% of a monthly bill. On a metered
  API the things that move 60% to 80% are which model the call goes to, the
  Batch API, prompt caching, and what re-sending the conversation costs — and
  "trazum profile <usage.jsonl>" prices all four from what the provider
  actually charged.

A tool whose first command reports 1% and says nothing about the other 99% has not told you what it knows.

Token counting

A dependency-free estimator with a band measured per kind of text — ±4% on CJK, ±6% on Latin prose, ±26% on code and markup, ±33% on tabular numbers — measured over 47 samples in ten languages, where the worst error in each bucket is 3.2%, 5.6%, 25.1% and 32.5%. Language-aware because one English divisor was 37% wrong on German. --exact-tokens settles any doubt against the provider's free counting endpoint. The measurement story is in the command reference.

Limitations, stated plainly

• Savings are projections, not billing. They are computed over the scenario you describe (calls/month, output tokens) using the table in packages/core/src/pricing.ts. Check that table before budgeting: PRICING_LAST_REVIEWED tells you when it was last updated.
• Output tokens are held constant in the calculation. A shorter prompt often produces somewhat shorter answers, but that depends on the task and cannot be promised. The saving shown comes from input only.
• The model recommendation is a keyword heuristic, not a judgement about answer quality. Measure the difference with your own evaluations before dropping a tier in production.
• The aggressive level can change nuance. It removes intensifiers, hedges and self-verification requests. Read the diff before applying it.
• Amazon Bedrock and Vertex AI pricing is set by each partner and is not the pricing in this table.

Layout

packages/core/     dependency-free library (rules, tokens, pricing, LLM)
  src/segment.ts     isolation of code, URLs, emails, templates and XML
  src/rules.ts       deterministic rules engine
  src/phrases.ts     phrase dictionaries (data, multilingual)
  src/pricing.ts     model and pricing catalogue
  src/structure.ts   contradictions and repeated few-shot examples
  src/similarity.ts  shared near-duplicate scoring
  src/advisories.ts  caching, batch, model and context advisories
  src/reorder.ts     moving blocks in front of the first placeholder
  src/compare.ts     comparePrompts — after minus before, positive is worse
  src/profile.ts     the measurements behind `rank`, and no score
  src/suggest.ts     phrase-level rewrites, and the checks each one passes
  src/promptfoo.ts   exporting a suite for somebody else's assertions
  src/extract.ts     prompts marked inside source files
  src/detect.ts      which provider a file actually calls
  src/llm.ts         pluggable providers and safety checks
  src/net.ts         endpoint validation, the allowlist, safe fetch defaults
  src/i18n/          message catalogues (report language)
  src/shared-prefix.ts  preambles that could share a cache entry and do not
  src/usage.ts       the usage-log profiler: where the money actually went
  src/levers.ts      what would move the bill, priced from tokens that were billed
  src/conversation.ts   what re-sending the conversation costs, a ceiling
  src/output-shape.ts   where the output spend concentrates: tail or task
  src/prune.ts       leave-one-out over few-shot examples, against the noise floor
  src/aws-sigv4.ts   Bedrock's signature, by hand, on WebCrypto
  src/gcp-auth.ts    Vertex's service-account JWT, same reasoning
  src/openrouter.ts  live prices, with the unknowns marked unknown
packages/cli/      dependency-free CLI
  src/markdown.ts    the report as markdown, and the three escapers
  src/git.ts         the only module here that runs another program
packages/mcp/      dependency-free MCP server — twelve tools over stdio in this checkout
  src/rpc.ts         JSON-RPC 2.0 by hand; the invariant beat the SDK
  src/tools.ts       the whole surface an agent can reach, in one file
packages/tokenizer-openai/   optional exact counter, and the only dependency here
  src/index.ts       OpenAI's own ranks; refuses a model it has no table for
apps/web/          Next.js (App Router) — Optimise, Compare, Your bill, Library
action/            the packaged GitHub Action that comments on pull requests
scripts/           release notes, the token-band harness, rollback recovery
  draw-architecture.mjs  redraws the picture above from the workspace globs
  build-wiki.mjs     rebuilds wiki/ from this file, verbatim, section by section
wiki/              the GitHub wiki, generated — every page is a section of a
                   document above, so there is nothing here to keep in sync

Updating prices

packages/core/src/pricing.ts is the single source of truth, reviewed on a stated date; overlays (--pricing) and the live OpenRouter feed (--pricing-live) correct it without an upgrade. The recipe and its guards are in the command reference.

Analytics and privacy

There are two configurations and they have different answers. Both are stated here because the short version was wrong: this section said prompts are never stored on any server, without qualification, for several releases after the prompt library shipped and made that conditional.

• Signed out — the default. Nothing about a prompt is written server-side. Optimisation is synchronous: the response carries the result, and history lives in the browser's localStorage. This is what a deployment does with no TRAZUM_GITHUB_CLIENT_ID configured, and signing in cannot be switched on by a visitor.
• Signed in, with the prompt library. Saving a prompt writes its text to Postgres — trazum_prompt_versions.text, one row per version, because a library that cannot show you yesterday's wording is not a library. Nothing is written until you save, and the database is the operator's rather than ours. docs/accounts.md is the full account, including the row level security the schema turns on and why it uses ENABLE and not FORCE.
• Analytics (PostHog) is off by default and never sends prompt content — only aggregate metrics (reduction percentage, level, model, locale). It switches on only when the operator sets NEXT_PUBLIC_POSTHOG_KEY, which also adds the analytics origin to the Content-Security-Policy; with no key the policy stays connect-src 'self'. When it is on, the only events sent are the ones the app names: autocapture, automatic pageviews, session recordings, heatmaps and surveys are switched off by name, nothing is kept in a cookie, and every URL an event carries has its share token replaced (/c/:token) and its query dropped before it leaves the browser.
• LLM keys entered in the UI are used for that request and discarded; they are neither logged nor persisted.

The rest of the documentation

This README is the overview. Tutorials, integration recipes and reference material have their own pages. docs/README.md is the index, arranged by what you came here to do rather than by what the files are called: choosing the tool, using it, extending it, maintaining it, or reporting a problem.

The four you are most likely to want directly:

• docs/doctrine.md — the rules this product refuses to break, each one discovered by getting it wrong first. It is the argument for why a figure printed here is worth reading.
• docs/our-own-medicine.md — the same standard turned on this project: what it refused to ship, what it got wrong and for how long, and what it cannot say about itself.
• docs/usage-logs.md — what Trazum can read from your logs, and what each optional field unlocks if you start writing it.
• docs/json-output.md — every machine-readable document, field by field, with the provenance each one carries.

Roadmap and contributing

ROADMAP.md covers what is planned and why, and the history that got here, oldest first. CONTRIBUTING.md covers adding a rule or a language, and docs/authoring-rules.md is the full walkthrough for a rule. VERSIONING.md covers what counts as public API. CODE_OF_CONDUCT.md covers what is expected of everyone taking part, and is honest about what a single-maintainer project can promise. SUPPORT.md covers what gets answered and how fast; SECURITY.md covers reporting a vulnerability privately.