Save Money and Tokens With Compression

Every token your AI agent processes costs money. When Tarsk searches your codebase with grep or lists files with find, the raw output goes straight into the conversation context. A grep search across 200 files can dump 15KB of text into a single API call. The model tokenizes and bills that text on every call. Multiply that by dozens of tool calls per session, and the cost adds up.

Tarsk compresses tool output before the model sees it. You pay for fewer tokens, and the model responds faster because it has less text to read.

Your Token Budget

A single coding session with an AI agent involves repeated tool calls. The agent searches for functions, reads files, greps for patterns, lists directories. Each call returns text that becomes part of the next prompt sent to the model.

A typical 30-minute session fills the context window like this:

• Your messages and system prompt: 2,000 to 4,000 tokens
• Tool definitions (schemas the model needs to call tools): 3,000 to 5,000 tokens
• Tool outputs (search results, file contents, directory listings): 10,000 to 50,000+ tokens
• Model responses: 5,000 to 15,000 tokens

Tool outputs dominate. They are the largest and most variable part of every request. A find operation on a large project returns hundreds of file paths. A grep for a common term like "import" or "return" can match thousands of lines across the codebase. All of that text re-enters the context on every subsequent model call.

You pay per token on every request. The model does not remember previous calls; it reads the full conversation history each time. So a 30KB tool output that appears in turn 3 still costs you tokens in turn 12, turn 20, and turn 30.

What Compression Does

Tarsk applies lossless compression to tool output before it enters the conversation. The model receives the same information in fewer bytes. Every piece of data survives; the compressed output reverses back to the original.

Compression kicks in automatically, and you see two effects:

1. Lower cost and faster responses. The model processes less text per call, so each API call costs less and returns sooner.
2. More room in the context window. Compressed output leaves space for longer conversations before you hit the context limit.

You do not need to configure anything. Compression runs automatically when tool output meets the threshold. Your Daily Spend widget in Tarsk tracks how many bytes compression has saved, so you can see the effect in real time.

How Much You Save

The savings depend on your project size and what the agent does. Some benchmarks from real sessions:

File search (find). A find across a medium project returns 150 file paths. The flat listing is roughly 4.5KB. After compression, the same listing is roughly 1.8KB. That is a 60% reduction.

Code search (grep). A grep for a function name across 80 files returns 200 matching lines. Flat output: 12KB. Compressed: 5KB. Roughly 58% smaller.

Content search (grep with context). When the agent greps with surrounding lines, output grows fast. A search returning 50 matches with 3 lines of context each produces 20KB of output. Compression brings that down to around 9KB.

Over a full session with 20 to 40 tool calls, compression can save 100KB to 300KB of raw text. At typical token densities (roughly 4 characters per token), that translates to 25,000 to 75,000 fewer tokens per session. On Claude Sonnet at $3 per million input tokens, a session with 50,000 compressed-away tokens saves $0.15 per call where that output appears in context. Across 15 calls, that is $2.25 saved in a single session.

On GPT-5.4 at $2.50 per million input tokens, the math is similar. Across a workweek of heavy agent use, compression can cut your input token bill by 20 to 40 percent.

Speed Gains

Fewer tokens mean faster responses. The model's prefill step (reading your input before generating) scales linearly with input length. Cut the input in half, and prefill takes half the time.

On a typical session with 25,000 tokens of tool output in context, compression removes roughly 12,000 tokens. That shaves 1 to 3 seconds off each response, depending on the model and provider. Across 30 tool-call rounds in a session, you save 30 to 90 seconds of total wait time.

Faster individual responses mean the agent completes multi-step tasks sooner. A task that involves 10 rounds of search-and-edit finishes faster when each round processes less input.

Track Your Savings

Tarsk's Daily Spend widget shows compression savings alongside your token usage and cost. Open the widget to see:

• Bytes saved today from tool output compression
• Bytes saved over the last 30 days
• Input and output token counts broken out separately

Tarsk tracks cumulative bytes saved across all tool calls. The number updates after every session.

The widget sits in the title bar. One click shows today's cost, 30-day totals, token breakdowns, and compression savings in a single dialog.

How It Works — The Compression Engine

Tarsk's tool output compression uses three techniques that run in sequence, each targeting a different type of redundancy. The system picks the technique that fits the output format, applies it, and verifies that the result is smaller before committing. If compression would grow the output, the system falls back to the original text.

Directory Grouping

When a tool returns a list of file paths, most paths share common directory prefixes. A flat listing repeats those prefixes on every line:

cli/src/components/Button.tsx
cli/src/components/Header.tsx
cli/src/components/Footer.tsx
cli/src/utils/format.ts
cli/src/utils/parse.ts

Directory grouping collapses consecutive paths that share a parent directory into a single line:

cli/src/components/: Button.tsx, Header.tsx, Footer.tsx
cli/src/utils/: format.ts, parse.ts

Five lines become two. The directory prefix appears once instead of five times. The model can still reconstruct every full path from the grouped format.

The grouping preserves original order. Only consecutive entries that share a directory get merged. If paths from the same directory appear in different positions (separated by paths from another directory), they stay in separate groups. This keeps the transform lossless for both the set and the sequence of paths.

Common Prefix Stripping

When paths span multiple directories but share a root prefix, the system extracts that prefix once and strips it from every line. A header tells the model what was removed:

[relative to cli/src]
components/Button.tsx
components/Header.tsx
utils/format.ts

The prefix cli/src/ appears once instead of three times. This technique stacks with directory grouping: first strip the shared prefix, then group what remains.

The prefix calculation works on whole directory segments. It never splits a folder name in half. If paths diverge at the top level (one starts with app/, another with cli/), no prefix is extracted, and the output stays flat.

Grep Output Restructuring

Grep results carry more structure than file lists. Each match includes a file path, line number, and content. The default format repeats the file path on every matching line:

src/utils/format.ts:12:export function formatDate(date: Date) {
src/utils/format.ts:18:export function formatTime(date: Date) {
src/utils/format.ts:24:export function formatCurrency(amount: number) {
src/utils/parse.ts:5:export function parseDate(input: string) {
src/utils/parse.ts:11:export function parseAmount(input: string) {

The compression engine detects repeated paths and switches to a heading format, similar to how ripgrep displays results:

[relative to src/utils]
format.ts
12:export function formatDate(date: Date) {
18:export function formatTime(date: Date) {
24:export function formatCurrency(amount: number) {

parse.ts
5:export function parseDate(input: string) {
11:export function parseAmount(input: string) {

The file path appears once per file instead of once per match. For searches that return 5 matches per file across 40 files, this cuts path-related bytes by 80%.

The engine handles all three grep modes differently:

• Files mode (listing matching files): groups paths by directory, same as find.
• Count mode (showing match counts per file): groups paths and carries the count along.
• Content mode (showing matching lines): switches to the heading format described above.

Safety Guardrails

Compression never makes output larger. Every technique includes a size check that compares the compressed result against the original. If the compressed version plus the required banner text would exceed the original size, the system returns the original text untouched.

This matters because directory grouping can grow output when paths rarely share a directory. Five root-level files grouped with a banner would produce more bytes than the flat listing. The guardrail catches this and keeps the output flat.

Compression also requires a minimum item count before it activates. For find and grep, that threshold is 20 items. Below that, the overhead of the banner and grouping instructions would eat into the savings. Above it, compression kicks in automatically.

How Savings Are Tracked

Every time compression runs, Tarsk measures the byte difference between the original and compressed output. If compression reduced the size, Tarsk records the savings in your local database. The Daily Spend widget reads these numbers and displays them alongside your token costs.

The tracking is per-byte, not per-token, because byte count correlates with token count at a roughly fixed ratio (about 4 characters per token for English text and code). Showing bytes gives you a direct measure of how much text compression removed from your context window.

When Compression Matters Most

Large codebases. Projects with thousands of files produce large tool outputs by default. A find across a monorepo can return 2,000 paths. Compression cuts that to a fraction.

Search-heavy workflows. Sessions with many grep calls (searching for patterns, tracing function calls, finding usages) benefit the most. Each call adds compressed output instead of raw output.

Long sessions. Compression saves tokens on every tool call, and those savings grow across a session. A 40-round session benefits more than a 5-round one.

Small projects with 50 files and minimal search usage give compression less to work with. The feature runs the same way, but the inputs are smaller.

What You Get

Tool output compression runs silently. Tarsk compresses search results and file listings before the model reads them. You get the same answers from the agent, but you pay for fewer tokens and you wait less time for each response.

Check your Daily Spend widget after a few sessions. The compression savings line tells you how much text compression removed from your context. On active coding days with 20-plus tool calls, you will see tens of thousands of bytes saved. Lighter days produce smaller numbers, but compression runs on every tool call regardless.

Nothing to configure. The same information reaches the model in fewer bytes, and your spend widget shows the difference.