Trazum

<div align="center">

# Trazum

### Most of your LLM bill is not the prompt. Trazum finds where it is.

**A deterministic cost analyser for prompts and usage logs.** Offline, free,
same answer every time. It reports fifteen findings priced in dollars per
month: caching you are not getting, a model tier you may not need, a schema you
pay to describe on every call. Shortening the prompt is one of them, and it is
rarely the biggest.

[![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>

## 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. For any other MCP client,
`npx -y @trazum/mcp` over stdio does the same.

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

**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.** Fifteen 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 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/web       action/
 42 commands       MCP server      Next.js     comments on pull requests
                 for your agents
```

## Contents

- [What it actually does](#what-it-actually-does) — the five things, and what it refuses to touch
- [The forty-two commands](#the-forty-two-commands): the whole surface, one line each
- [Getting started](#getting-started) — CLI, web, the GitHub Action, pre-commit
- [The first five minutes](#the-first-five-minutes-trazum-init) — `init`, and the four things it refuses to write
- [Building on the format](docs/commands.md#building-on-the-format-trazum-conform) — the contracts, the guarantees, and the doctrine
- [More than one machine](docs/commands.md#more-than-one-machine-trazum-rollup) — several people's documents, one bill, every gap preserved
- [Did anything stop running](docs/commands.md#did-anything-stop-running-trazum-pulse) — the outside view of a scheduled job
- [Which few-shot examples earn their tokens](docs/commands.md#which-few-shot-examples-earn-their-tokens-trazum-prune) — measured, and it asks before spending
- [An MCP server for your agents](docs/commands.md#an-mcp-server-so-an-agent-can-budget-its-own-prompts) — budget a prompt before sending it
- [Languages](#languages) — what the dictionaries cover, and what they deliberately do not
- [Connecting your own LLM](#connecting-your-own-llm) — one wire format, four native providers, and the SSRF rules
- [Every model you pay for by the token](#every-model-you-pay-for-by-the-token) — pricing across seven providers, live via OpenRouter
- [Token counting](#token-counting) — the estimator, and the error band it prints
- [Limitations, stated plainly](#limitations-stated-plainly) — read this one
- [Running it on a schedule](docs/running.md) — cron, systemd, Actions, and where the answer runs out
- [Everything else](docs/README.md) — the documentation index, arranged by whether you are
  choosing this, using it, extending it or maintaining it
- [Layout](#layout) · [Updating prices](#updating-prices) · [Privacy](#analytics-and-privacy) · [Roadmap](#roadmap-and-contributing)

---

## What it actually does

**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 computed over the **real stable prefix**: in a template with `{{placeholders}}`, only what precedes the first one is cached — not the whole prompt. |
| Reorder the template | Stable instructions sitting *after* the first variable placeholder never cache today. Trazum prices moving them in front — and with `--reorder`, [does it](docs/commands.md#reordering-for-the-cache---reorder). |
| Batch API | 50% off input and output when the work tolerates latency. |
| Cheaper model | Complexity heuristic: if the task looks simple, what dropping a tier would save. |
| Output-dominated cost | If you pay more for the answer than for the prompt, shortening the prompt has a ceiling. |
| Promotional pricing | Warns when you are budgeting with an introductory price that expires. |
| Context window | If the prompt does not fit, the call is going to fail. |
| Contradictory instructions | "Answer in English" three paragraphs above "reply in the customer's own language". The model has to pick one, and which one can change between calls — a correctness problem that also costs tokens twice. |
| Redundant examples | Few-shot examples that are near-copies of an earlier one, and what they cost per month. |
| Output format stated twice | A schema shown in a code block and then walked again in prose. The block is the version worth keeping. |
| Schema the request could carry | A schema block introduced by "Output format:" is paid for in input tokens on every call. Every major API now takes a response schema as a *parameter* — and moving it there is both cheaper and stricter. See below. |

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.

#### The one finding that is not a trade-off

Most of what Trazum reports is a choice: shorter against clearer, cheaper against
more capable. Moving an output schema out of the prompt is neither.

```
→ The output schema could travel in the request instead of the prompt
  A schema block introduced by "output format" defines `category`, `reply`,
  `escalate_to_human`, `confidence`, costing about 62 tokens on every call.
```

Those tokens are paid on **every call** to have the model read a shape and be
asked, politely, to match it. `output_config.format`, `response_format`,
`responseSchema` — whatever your provider calls it — takes the same shape as a
request parameter, where the decoder is constrained rather than persuaded. Cheaper
*and* stricter.

**Trazum reports it and never does it**, because it is not a change to the prompt:
it is a change to the code that sends the prompt. A rule that deleted the schema
would leave a prompt asking for a shape it no longer describes, sent by a client
nobody updated — strictly worse than what it started from.

**The one way this could do harm, and what stops it.** `Output format: {...}` is
a contract and moving it is free; `Input: {...}` inside a few-shot example is
*data the prompt needs*, and moving it breaks the prompt. So nothing is guessed:
a block counts only when a phrase from the output-cue dictionary appears
immediately before it, in one of the seven languages the rules cover. No phrase,
no finding — a false negative, which is the right direction to be wrong in.

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 rul