rtk

How Savings Work

RTK reduces the bash output your agent reads. That is what RTK measures, and it is not the same as cutting your bill by the same amount.

Bash output is one contributor to input tokens, alongside your prompt, the system prompt and conversation history. Input tokens are in turn only part of the bill, which also counts output tokens. The reduction dilutes at every step.

The token counts RTK reports are estimated as bytes / 4 — RTK ships no tokenizer, so the percentages are reliable but the absolute token numbers are approximate.

Full explanation: How RTK Savings Work

Installation

brew install rtk                                              # macOS / Linux
winget install rtk-ai.rtk                                     # Windows
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

Then check you have the right package — another project named "rtk" exists on crates.io:

rtk --version   # any current version
rtk gain        # must show the savings dashboard, not "command not found"

Cargo, pre-built binaries, native Windows, WSL, and uninstall: Installation guide

What You Install

RTK ships as three downloads. The two rtk editions install a binary with the same name — hooks, scripts and agent config work unchanged across both — so they cannot be installed together. Uninstall one before installing the other.

flowchart TD
    agent["Your coding agent"]

    subgraph editions["Pick one · both install a binary named rtk"]
        direction LR
        full["<b>rtk</b><br/>Apache-2.0 + BUSL-1.1<br/>hooks · filters · engine"]
        oss["<b>rtk-oss</b><br/>Apache-2.0 only<br/>hooks · filters"]
    end

    proxy["<b>rtk-proxy</b><br/>BUSL-1.1<br/>compresses API traffic"]

    agent -->|"command output"| full
    agent -->|"command output"| oss
    agent -.->|"API traffic"| proxy

    classDef apache stroke:#2da44e,stroke-width:2px,fill:none
    classDef busl stroke:#0969da,stroke-width:2px,fill:none
    classDef mixed stroke:#8250df,stroke-width:2px,fill:none
    classDef plain stroke:#8c959f,stroke-width:1px,fill:none
    class full mixed
    class oss apache
    class proxy busl
    class agent plain
    style editions fill:none,stroke:#d0d7de,stroke-dasharray:4 4

Production use is free, engine and daemon included. What the BUSL grant does not cover is offering RTK or a derivative to third parties as a commercial product or service — for that, contact contact@rtk-ai.app.

curl -fsSL .../install.sh | RTK_EDITION=oss sh    # Apache-2.0 edition
brew install rtk-ai/tap/rtk-oss

What the Apache-2.0 edition omits and where the licence boundary falls: Editions and Licensing

Quick Start

# 1. Install for your AI tool
rtk init -g                     # Claude Code / Copilot (default)
rtk init -g --gemini            # Gemini CLI
rtk init -g --codex             # Codex (OpenAI)
rtk init -g --agent cursor      # Cursor
rtk init -g --agent windsurf    # Windsurf
rtk init --agent cline          # Cline / Roo Code
rtk init --agent kilocode       # Kilo Code
rtk init --agent antigravity    # Google Antigravity
rtk init --agent kimi           # Kimi AI
rtk init -g --agent pi          # Pi
rtk init --agent omp            # Oh My Pi (OMP)
rtk init --agent hermes         # Hermes
rtk init -g --agent droid       # Factory Droid
rtk init --agent trae           # Trae (project: .trae/hooks.json)
rtk init -g --agent trae        # Trae global: ~/.trae and existing ~/.trae-cn

# 2. Restart your AI tool, then test
git status  # Automatically rewritten to rtk git status

The agent receives compact output without ever calling rtk explicitly.

The hook only fires on Bash tool calls. Built-in tools like Read, Grep and Glob do not pass through it. Use shell commands (cat, rg, find) or call rtk read, rtk grep, rtk find directly.

Per-agent setup, --dry-run, and uninstall: Quick Start · Supported Agents

How It Works

  Without rtk:                                    With rtk:

  Claude  --git status-->  shell  -->  git         Claude  --git status-->  RTK  -->  git
    ^                                   |            ^                      |          |
    |         full raw output           |            |  compact output      | filter   |
    +-----------------------------------+            +------- (filtered) ---+----------+

Four strategies applied per command type:

1. Smart Filtering - Removes noise (comments, whitespace, boilerplate)
2. Grouping - Aggregates similar items (files by directory, errors by type)
3. Truncation - Keeps relevant context, cuts redundancy
4. Deduplication - Collapses repeated log lines with counts

Does RTK break Claude's prompt cache? No. RTK filters output once per command. The result is stored in history and cached normally on subsequent API calls, so the cache keeps working as expected. Smaller outputs also mean cheaper cache writes and reads. See Troubleshooting for details.

Supported AI Tools

RTK supports 18 AI coding tools. Each integration rewrites shell commands to rtk equivalents, reducing the bash output the agent reads where the agent supports command interception.

For per-agent setup details, override controls, and graceful degradation, see the Supported Agents guide. The Hermes plugin source and tests live in hooks/hermes/; installed Hermes runtime files still live under ~/.hermes/plugins/rtk-rewrite/.

What RTK Covers

100+ commands across Git, GitHub CLI, Cargo/Rust, JavaScript (npm, pnpm, vitest, jest, tsc, Next.js, Playwright, Prisma), Python (ruff, pytest, mypy, pip), Go (go test, golangci-lint), Ruby, .NET, JVM (Gradle, Maven), PHP, Docker, Kubernetes, AWS, Terraform, and the file/search builtins.

-v, --verbose          # increase verbosity (-v, -vv, -vvv)
rtk bypass <cmd>       # run one command unfiltered, still tracked

Every command and its filter: What RTK Optimizes

Escape hatches

rtk filters command output by default. When a result looks wrong, bypass the filter for one command to see the raw output and tell a filter bug apart from the real thing:

rtk bypass git log --oneline -20        # full git log, no truncation
rtk bypass npm install express          # raw npm output, no filtering
rtk bypass curl https://api.example.com/data

• What it does: runs one command unfiltered and still tracks it — bypassed commands appear in rtk gain --history with 0% bash output reduction.
• When to use it: an output looks off and you need to know whether the filter or the command produced it, when debugging a filter, or for an edge case a filter mishandles.
• rtk proxy <cmd> is a deprecated alias of rtk bypass <cmd>.

Not the same thing as rtk llm-proxy. rtk bypass runs one local command unfiltered. rtk llm-proxy manages the rtk-proxy daemon, which compresses your agent's provider-API traffic — see RTK Proxy.

Measure It

rtk gain                        # Summary stats
rtk gain --graph                # ASCII graph (last 30 days)
rtk gain --history              # Recent command history
rtk gain --daily                # Day-by-day breakdown
rtk gain --all --format json    # JSON export for dashboards

rtk discover                    # Find missed savings opportunities
rtk discover --all --since 7    # All projects, last 7 days

rtk session                     # Show RTK adoption across recent sessions

Attribution, the live dashboard and export formats: Token Savings Analytics

RTK Proxy (optional)

rtk optimizes command output before your agent reads it. The rtk-proxy daemon extends the same engine to your agent's provider-API traffic — a local background process that sits between your agent and the provider and runs the pipeline on the traffic itself: it compresses payloads, strips bytes no model ever needed before forwarding, and carries the calls your pipeline routes to cheaper models, so they borrow the credential your agent already sends and show up in rtk gain. It can also align prompt-cache breakpoints where the agent leaves them open (opt-in).

rtk claude              # start the daemon if needed, then launch Claude through it
rtk llm-proxy status    # is it up
rtk gain                # savings, command-filtering and proxy side by side

Two independent ways in, because not every harness has a session hook:

rtk <harness> resolving is itself the signal that traffic really goes through the daemon — the subcommand exists only where redirection is verified. Today that is rtk claude. A harness without one is never silently unproxied: it falls through to plain passthrough, and rtk llm-proxy setup lists what can be launched.

It is a separate binary under a separate licence (BUSL-1.1), shipped as its own rtk-proxy-<target> archive — rtk never links it.

Setup and subcommands: RTK Proxy · what it compresses: What the Proxy Compresses · settings and endpoints: Proxy Configuration

The Engine (pipeline.toml)

Everything RTK does — which commands get rewritten, what happens to a tool's output, what the proxy compresses — is expressed in one composable file. The engine (engine/, crate rtk-engine, BUSL-1.1) reads it, so the levers are configurable instead of hard-coded.

Upgrading changes nothing. With no pipeline file you are on rtk:default: the same PreToolUse rewrite, the same awareness file, your filters.toml, your config.toml. Everything beyond that is opt-in, one line at a time:

# ~/.config/rtk/pipeline.toml
[pipeline]
extends = ["rtk:posthook", "rtk:proxy"]

The tour: Pipelines · the reference: Writing a Pipeline, Conditions and Judges, Methods, Tasks and Upstreams · the commands: Pipeline Commands · write your own method: Plugins

Documentation

rtk-ai.app/guide is the full user guide.

Repository references: engine/README.md · proxy/README.md · ARCHITECTURE.md · CONTRIBUTING.md · SECURITY.md

RTK collects no command content and no file contents. Telemetry is anonymous and off by default — it sends nothing until you opt in with explicit consent (GDPR Art. 6 & 7) via rtk telemetry enable, and documented in Telemetry & Privacy.

Star History

StarMapper

Core team

• Patrick Szymkowiak — Founder GitHub · LinkedIn
• Florian Bruniaux — Core contributor GitHub · LinkedIn
• Adrien Eppling — Core contributor GitHub · LinkedIn
• Nicolas Le Cam — Core contributor Github · LinkedIn
• Takayuki Maeda — Core contributor GitHub · LinkedIn

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

Join the community on Discord.

License

The rtk CLI is Apache-2.0 — see LICENSE.

It links one component under a different licence. rtk-engine (engine/) is BUSL-1.1, source-available: see engine/LICENSE. Its Additional Use Grant permits production use as part of the rtk binary, so running rtk is covered; using the engine on its own, or inside another product, is not until the Change Date.

The rtk-proxy daemon (proxy/) is BUSL-1.1 on the same terms and ships as its own archive with its licence alongside — rtk never links it.

RTK Pro

Your company is looking to take control back on your AI fleet ? RTK Pro provides the control layer for costs, security and governances for all agents.

Check it out : RTK Pro.

Disclaimer

See DISCLAIMER.md.