The branch discrepancy is explainable: releases are cut from master while develop lives its own life. But installing with cargo install --git and no branch will not give you what the latest release contains - the analytics documentation shows the install with an explicit --branch master for a reason.

One more detail you hit within the first minute: the README still suggests verifying the install with rtk --version # Should show "rtk 0.28.2". That is a stale example, not the current version.

How an ordinary command becomes its shorter self

In its simplest form a prefix is added:

From there RTK takes six steps: it parses the arguments, routes the call to the module for that specific command, runs the real tool, filters its output, prints the result and writes a couple of numbers into a local database. The exit code is preserved throughout - otherwise the filter would break any CI pipeline.

Note what is absent from that chain. RTK does not call a second model to summarise the output. All filtering is parsers and rules inside the binary, so it carries neither an inference bill nor a network round trip.

Six strategies rather than one summariser

Different commands are noisy in different ways, and a single algorithm does not fit. The architecture documentation lists six techniques and names who uses each.

The most obvious win is where success is verbose and only failure matters. A test run prints pages of "PASS" for the sake of one broken file, and that class of command sits at the top of the official tables.

How much comes off specific commands

The official table gives per-command figures rather than one blanket number. Here is a representative selection.

If a command is not on the list, it passes through untouched and lands in the statistics with zero savings. There is also a global --ultra-compact flag that squeezes output further; for git commands the docs recommend the long form only, because git's own -u means --set-upstream.

Installing takes one line, but there is a name trap

On macOS the recommended route is Homebrew:

The universal script for Linux and macOS installs the binary into ~/.local/bin:

Building from source, with an explicit branch so you do not catch develop:

Now the trap. There is another project named rtk on crates.io - Rust Type Kit - and the README warns about the collision in its own callout. The check is simple: the correct RTK has a rtk gain command.

If rtk --version works but rtk gain is not found, the wrong package is installed.

Wiring it to an agent: interception for some, persuasion for others

Next the agent needs to stop having to remember the prefix. For Claude Code that is one command:

Alongside the hook, rtk init drops an RTK.md file describing the commands - a fallback in case interception does not fire and the agent has to follow instructions instead. There is a --dry-run mode that shows the upcoming changes without writing anything.

The mechanism is the same for every agent: the hook catches a command, calls rtk rewrite, receives the rewritten variant and substitutes it before execution. All rewrite logic lives in the binary; the integrations are thin adapters that parse each client's event format.

But the integration tiers differ, and that is the key thing to understand before installing.

Transparent interception exists for Claude Code, Cursor, Gemini CLI, both flavours of GitHub Copilot, Factory Droid and Mistral Vibe; plugins cover OpenCode, OpenClaw, Pi and Hermes. Codex CLI, Cline, Roo Code, Windsurf, Kilo Code and Google Antigravity get only a rules file. The difference matters: in the first case the substitution is guaranteed, in the second it depends on whether the model remembers the instruction.

A separate caveat about Claude Code. The hook is attached to the Bash tool, so the built-in Read, Grep and Glob never pass through it - they are not shell calls. The line "RTK automatically saves Claude Code tokens" holds for shell commands and does not hold for reading and searching through built-in tools. If the filter is wanted there too, the agent has to call rtk read, rtk grep, rtk find explicitly.

On native Windows there is no full interception either: rtk init -g falls back to injecting instructions into CLAUDE.md, the filters themselves work, automatic rewriting does not. The complete setup runs through WSL.

The hooks are built never to get in the way. Missing binary, a version that is too old, malformed JSON on input, a crash inside rtk rewrite - in every case the hook exits zero and the command runs unmodified.

Where RTK keeps its files - and where the documentation is wrong

This is worth checking on your own machine rather than in the docs.

The analytics page gives the database as ~/.local/share/rtk/history.db and labels it "Linux / macOS". In the code the path comes from the system function dirs::data_local_dir(), which on macOS returns somewhere entirely different. The check takes a second:

So on macOS the database, the saved-output directory and the user filters all live in ~/Library/Application Support/rtk/, and no ~/.local/share/rtk appears at all. The configuration page, incidentally, gets it right for the config file - ~/Library/Application Support/rtk/config.toml - while the analytics and privacy pages kept the Linux paths.

The practical consequence: documentation commands like sqlite3 ~/.local/share/rtk/history.db ... simply will not find the file on a Mac, which reads as "RTK recorded nothing" when in fact it recorded everything.

The discrepancy runs deeper than it looks, and it lives right inside the sources. The file src/core/tracking.rs opens with a comment naming the database tracking.db and carefully spelling out paths for three platforms. But the path below it, in the same file, is assembled from the HISTORY_DB constant - and that constant equals history.db. Some documentation pages copied the name from the comment and some from the code, so across the project the database goes by two different names. The constant is the one that is right.

Measure, do not believe: gain, discover and session

Three commands answer three different questions.

rtk gain answers how much output has already been cut.

The table has five columns: number of commands, input tokens before filtering, output tokens after, the difference and the percentage. Only the last one carries meaning - it is a byte ratio, and it is honest. The other four are built on dividing by four. The --quota flag converts the savings into a share of a monthly plan allowance (-t pro, -t 5x, -t 20x), and it too should be read as an order of magnitude.

rtk discover answers the opposite question - what slipped past the filter. It parses Claude Code command history and shows where savings were missed.

rtk session shows coverage across recent sessions: how many shell commands went through RTK and how many stayed raw.

That last command is more useful than it looks. A filter with an excellent compression ratio is worthless if the agent bypasses it half the time, and coverage is the only way to notice. Low numbers usually mean RTK_DISABLED=1 was set somewhere, or the hook did not attach for a subagent.

The right sequence, if you want to understand the benefit for yourself: install it, wire it up, optimise nothing in particular for a week, then look at rtk gain --daily, rtk session and rtk discover --all --since 7. Your own mix of commands will say more than any table on a landing page.

Compressed does not mean discarded

Every lossy filter carries the same risk: throwing away the line that turns out to be the only important one a minute later. RTK answers that with a mechanism for preserving the full output.

When a command fails, the complete raw output is written to a file and the agent receives a short summary plus the path:

That example comes from the documentation and its path is the Linux one; on macOS the directory sits next to the database, under Application Support. By default the saving triggers on failures:

Output shorter than 500 bytes is not saved - there is nothing to rescue; anything above a megabyte is truncated; the last twenty files are kept. The difference from plain "truncate and forget" is substantial: the model gets a short answer now, but the details do not vanish permanently and do not require re-running the command.

When the filter gets in the way

Sometimes shortening is not acceptable - resolving conflicts, a manual rebase, any operation where byte-for-byte matters. For a single call an environment variable is enough:

For permanent exclusions, a list in the configuration:

Patterns are matched against the full command after environment prefixes are stripped, so "psql" also excludes PGPASSWORD=x psql -h localhost. Subcommands work: "git push" excludes git push origin main but leaves git status alone. A pattern starting with ^ is treated as a regular expression, and an invalid expression silently falls back to prefix matching.

Compound commands are handled separately, and the logic there is cautious. The &&, || and ; operators are rewritten on both sides:

Pipelines cannot be treated that way: substituting an intermediate stage would break the data flow. So producers and intermediate stages stay raw, only the final stage is rewritten, and only when it is pipeline-safe - today that is a limited set of grep, rg and wc invocations. A pipeline using |& is left alone entirely. A command that already starts with rtk is not wrapped twice.

Custom filters, and why you have to trust them by hand

The built-in rules are not the end of it. A custom filter is described in TOML and placed in one of two locations: .rtk/filters.toml in the project root - so it travels with the repository - or a user-level filters.toml that applies across all projects. This is useful for internal utilities and corporate scripts RTK knows nothing about.

But here the project takes a step worth noting. A filter from a repository is not applied merely because it is there. An untrusted file is silently skipped, and trust is granted explicitly:

Trust is bound to the file contents through SHA-256, so editing a trusted filter requires confirming again. The reasoning is straightforward: a filter decides which version of reality the model sees. A malicious rule in someone else's repository could hide errors or misrepresent output, and explicit confirmation is as justified here as it is for build hooks.

A note on upgrading: earlier versions applied the user-global file with no trust at all. After moving to a current version it has to be confirmed once as well.

The little-known one: rtk learn

There is a command in the list that almost nobody writes about. rtk learn parses Claude Code error history looking for repeated command-line mistakes - the ones where the agent keeps confusing a flag or the syntax.

With --write-rules the findings are written into .claude/rules/cli-corrections.md, turning them into a permanent correction for the agent. The confidence threshold is configurable (--min-confidence, 0.6 by default), as is the minimum number of occurrences. This has nothing to do with token savings, but the logic is the same: do not make the model rediscover a rake the data already knows about.

Telemetry: off by default, even though the sample config says otherwise

It is important not to repeat the common claim that RTK has no telemetry. It does, and it is worth understanding from the code rather than from a single documentation page.

The privacy page states it plainly: telemetry is disabled by default and requires explicit consent during rtk init or through rtk telemetry enable. The code backs that up - the send path passes through two consecutive checks and aborts immediately without recorded consent. The configuration page, however, shows a "full config structure" containing enabled = true in the telemetry section, which on a quick read looks like an on-by-default state. That is an error in the example, not in the behaviour.

With consent given, what leaves is aggregate: an anonymous device hash, version, OS and architecture, install method, command counts, popular tool names without arguments, the savings estimate and a few filter-quality metrics. What does not leave is source code, full command lines, paths, secrets, repository names and personal data. Server-side records are kept for at most twelve months, the local database for ninety days.

How sensitive a spot this is

It is worth remembering where RTK lives. The hook intercepts shell commands before execution, and the binary itself launches external tools. This is not a text formatter, it is part of the execution chain.

The project takes that seriously and its security policy lists the high-risk files: the command execution engine, output aggregation, the tracking database, the rewrite registry, the agent hooks, container operations, the dependency manifest and the CI pipelines. Changes there require two reviewers, and every pull request runs through cargo audit, a dangerous-pattern scan and lints.

The same caveat applies as with the paths: the security policy is dated 5 March 2026 and points at files such as src/runner.rs and src/tracking.rs, which have since moved into the src/core/ subdirectory. That is not a hole, but it is a sign that documentation trails the code - worth keeping in mind before reading any of its claims as final.

The practical conclusion is simple. If RTK is installed globally and rewrites the agent's commands automatically, upgrading it blindly is no more sensible than doing so with a shell plugin or a package manager hook. And for particularly sensitive operations there is RTK_DISABLED=1 and the exclusion list.

What was double-checked

Where RTK stands next to pxpipe and Headroom

The three projects in this series solve one problem at three different points.

Their relationship is layered rather than competitive. RTK works earliest of the three - it reduces the noise at the source, before it becomes a context management problem at all. The sensible order is: first do not generate the surplus lines, then decide whether what remains still needs compressing.

Conclusion

RTK takes a narrow problem and solves it without promising to fix context as a whole. For an agent that lives in a terminal the point is well chosen: tests, git, linters, package managers and containers run constantly, and their output was designed for a person, not for an expensive context window.

Its strengths are locality, speed, command-aware parsing without a second model, an honest caveat about what is being measured, preservation of full output on failure, and three commands for measuring the benefit yourself. Its weak spot is shared with every lossy filter: some lines disappear, and the decision is made by a rule rather than a person.

The correct phrasing is not "saves 90% of tokens" but "removes a significant share of the shell output that would otherwise reach the context". How much that reduces the bill depends on how large a share of your context the terminal was. If it was a large one, RTK looks less like an exotic compressor and more like a normal layer between the agent and its noisy tools.

Sources

The material was verified on 13 August 2026 against the repository and the project's official documentation. Versions and metadata were checked against the master branch and the GitHub API; telemetry behaviour and file paths were checked in the source code and on a working macOS machine, not only in the documentation. Discrepancies between the documentation and the code were not smoothed over but collected in a separate table. Supplemented on 15 August 2026 against a fresh clone: versions, the release, the star count and the strategy and per-command tables were re-checked and held; the mismatch in the database name inside the source itself was added.

• GitHub - rtk-ai/rtk
• Releases - v0.45.0
• README - installation, coverage, name collision warning
• How RTK Savings Work
• What RTK Optimizes
• Supported Agents
• Configuration
• Token Savings Analytics - rtk gain
• Discover and Session
• Telemetry & Privacy
• Architecture
• LLM Agent Hooks
• SECURITY.md