Trazum

<div align="center">

# 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**

[![CI](https://github.com/Davmunrey/Trazum/actions/workflows/ci.yml/badge.svg)](https://github.com/Davmunrey/Trazum/actions/workflows/ci.yml)
[![CodeQL](https://github.com/Davmunrey/Trazum/actions/workflows/security.yml/badge.svg)](https://github.com/Davmunrey/Trazum/actions/workflows/security.yml)
[![MIT licence](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A520-3c873a.svg)](package.json)
[![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-2f855a.svg)](#layout)

</div>

## Start here: one command, no global install

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

```bash
npx @trazum/cli bill
```

<div align="center">

<img src="docs/assets/bill.svg" alt="trazum bill on two illustrative Claude Code projects: $12.70 across 126 priced calls, a table by project and one by model with each share as a bar, Claude Fable 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5 each priced at its own rate" width="690">

*Illustrative data from [`examples/claude-projects`](examples/claude-projects),
not a customer result. Generated from the CLI output.*

</div>

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:

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

[Supported inputs](docs/usage-logs.md) ·
[Try sample data in your browser](https://trazum.vercel.app/?tab=playground)

## 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](docs/quick-start.md).
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](docs/quick-start.md#subscription-efficiency).

## Keep or share a report

```bash
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.

| You need | Start here |
|---|---|
| A terminal report | [Quick start](docs/quick-start.md) |
| Native agent session import | [Claude Code](docs/commands.md#the-agents-own-bill-trazum-from-claude-code) or [Codex](docs/codex.md) |
| An agent integration | [CLI, MCP and skill workflows](docs/agents.md) |
| An API contract or enforced call path | [Local HTTP API](docs/api.md) or [gateway](docs/gateway.md) |
| The full documentation | [Task-based index](docs/README.md) |

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.

<details>
<summary>Explore advanced workflows, commands, architecture and limitations</summary>

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

```bash
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:

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

The server is listed on the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Davmunrey/trazum)
as `io.github.Davmunrey/trazum`, and every release updates the listing.

**[Or run it right now, without installing anything: the Playground](https://trazum.vercel.app/?tab=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

<div align="center">

<img src="docs/assets/demo.svg" alt="trazum optimize on a wordy support prompt: 238 tokens down to 142 (-40.3%), $24.00/month saved by the rules, and an advisory pointing at $528.40/month, 22 times more" width="760">

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

</div>

<div align="center">

<img src="docs/assets/boundary.svg" alt="What goes in: a prompt or a usage log. What is computed on your machine, offline: @trazum/core with zero dependencies, plus the CLI, the MCP server, the web app and the Action. What leaves: a receipt, a report, a gate verdict. What never crosses the line: the prompt text, the model's answer, file paths, branch names and credentials." width="880">

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

</div>

**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/
 53 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

| I want to… | Go to |
|---|---|
| Get a first result | [Quick start](docs/quick-start.md) |
| Understand recorded spend | [Usage inputs](docs/usage-logs.md) and [bill/profile](docs/commands.md#find-a-command) |
| Set budgets | [CI gates](docs/ci.md) or [gateway decisions](docs/gateway.md) |
| Integrate Trazum | [CLI, web, library and agents](docs/setup.md) |
| Find a command or a data contract | [Command reference](docs/commands.md) and [documentation index](docs/README.md) |

[Limitations](#limitations-stated-plainly) · [Privacy](#analytics-and-privacy) ·
[Pricing](#every-model-you-pay-for-by-the-token) · [Contributing](CONTRIBUTING.md)

## 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:

| Advisory | Why it matters |
|---|---|
| Prompt caching | Reading from cache costs 10% of input. The saving is co