rtk

Agent-agnostic token optimization: compress, route, filter, and more.

One composable pipeline across everything your AI agent reads and sends — built on RTK's battle-tested bash-output compression (up to 90% smaller).

Website • Install • Troubleshooting • Architecture • Discord

English • Francais • 中文 • 日本語 • 한국어 • Espanol • Português

---

rtk filters and compresses command outputs before they reach your LLM context. Single Rust binary, 100+ supported commands, <10ms overhead.

Angular builds are supported with rtk ng build: compact build tables with every bundle and diagnostic retained.

What RTK Does

RTK intercepts shell commands and compresses their output before your agent reads it.

Operation	What RTK does to the output
ls / tree	Tree format with file counts instead of one line per entry
cat / read	Smart file reading: signatures and structure over full bodies
grep / rg	Truncates long lines, groups matches by file
ast-grep	Groups structural matches by file, caps overflow
git status	Compact stat format, grouped by state
git diff	Reduced context, headers stripped
git log	Hash, author and subject only
git add/commit/push	Confirmation line instead of full progress output
cargo test / npm test	Failures only, passing tests collapsed to a count
ruff check	Grouped by rule and file
sqlfluff lint	Grouped by rule and file
pytest	Failures only, traceback trimmed
go test	NDJSON parsed, failures only
docker ps	Essential fields only

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

Download	Licence	Contains
rtk-<target>	Apache-2.0 + BUSL-1.1	Hook core, every command filter, and the compression engine
rtk-oss-<target>	Apache-2.0 only	Hook core and every command filter. No engine.
rtk-proxy-<target>	BUSL-1.1	The RTK Proxy daemon. Never bundled with either rtk.

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.

Tool	Install	Method
Claude Code	rtk init -g	PreToolUse hook (native binary)
GitHub Copilot (VS Code)	rtk init -g --copilot	PreToolUse hook — transparent rewrite
GitHub Copilot CLI	rtk init -g --copilot	PreToolUse deny-with-suggestion (CLI limitation)
Cursor	rtk init -g --agent cursor	preToolUse hook (hooks.json)
Gemini CLI	rtk init -g --gemini	BeforeTool hook
Codex	rtk init -g --codex	PreToolUse hook (updatedInput) + AGENTS.md
Windsurf	rtk init -g --agent windsurf	.windsurfrules (project-scoped)
Cline / Roo Code	rtk init --agent cline	.clinerules (project-scoped)
OpenCode	rtk init -g --opencode	Plugin TS (execute.before / tool.execute.before), needs 1.18.29 or newer
OpenClaw	openclaw plugins install ./openclaw	Plugin TS (before_tool_call)
Pi	rtk init -g --agent pi (global)	TypeScript extension (tool_call)
Oh My Pi (OMP)	rtk init -g --agent omp (global) / rtk init --agent omp (project)	TypeScript extension (tool_call, shared with Pi)
Hermes	rtk init --agent hermes	Python plugin adapter (terminal command mutation via rtk rewrite)
Mistral Vibe	rtk init -g --agent vibe	pre_tool hook (hooks.toml)
Kilo Code	rtk init --agent kilocode	.kilocode/rules/rtk-rules.md (project-scoped)
Google Antigravity	rtk init --agent antigravity / rtk init -g --agent antigravity	.agents/plugins/rtk/ (project) or ~/.gemini/config/plugins/rtk/ (global): plugin.json, hooks.json, rules/AGENTS.md
Kimi AI	rtk init --agent kimi	AGENTS.md (project-scoped)
Factory Droid	rtk init -g --agent droid (or per-project)	PreToolUse hook in ~/.factory/hooks.json (matcher Execute)
Trae	rtk init --agent trae	Native PreToolUse hook in .trae/hooks.json (RunCommand)
Trae (global)	rtk init -g --agent trae	~/.trae/hooks.json, plus ~/.trae-cn/hooks.json when that directory exists

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

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:

	What it does
rtk init -g	Offers to set it up once: writes the base URL and the rtk:proxy pipeline, then asks how the daemon should come back after a reboot — SessionStart hook, background service, or neither.
rtk <harness>	No configuration at all. Starts the daemon, points the harness at it, then execs it. Needs no hook system, which is why it covers harnesses that have none.

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.

Installation	every install method, Windows, WSL, uninstall
Quick Start	per-agent init, --dry-run, first savings
Supported Agents	setup detail, override controls, degradation
Agent Coverage	what each agent's hook API lets RTK do
What RTK Optimizes	every command and its filter
Configuration	config.toml, env vars, recall recovery
Token Savings Analytics	rtk gain in full
Pipelines	the engine: pipeline.toml, rules, judges, tasks, sharing
RTK Proxy	the daemon: setup, what it compresses, settings
Editions and Licensing	what each download contains
Telemetry & Privacy	what is collected, how to opt in, your GDPR rights
Troubleshooting	common issues, prompt-cache questions

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.

Disclaimer

See DISCLAIMER.md.

高性能 CLI 代理，为你的智能体削减多达 90% 的 bash 输出

官网 • 安装 • 故障排除 • 架构 • Discord

English • Francais • 中文 • 日本語 • 한국어 • Espanol

---

rtk 在命令输出到达 LLM 上下文之前进行过滤和压缩。单一 Rust 二进制文件，零依赖，<10ms 开销。

RTK 做什么

RTK 拦截 shell 命令，在你的智能体读取之前压缩其输出。

操作	RTK 对输出做了什么
ls / tree	用带文件计数的树形格式代替每个条目一行
cat / read	智能文件读取：保留签名和结构，而非完整函数体
grep / rg	截断超长行，按文件分组匹配结果
git status	紧凑的 stat 格式，按状态分组
git diff	减少上下文，去掉头部信息
git log	仅保留哈希、作者和标题
git add/commit/push	用一行确认代替完整的进度输出
cargo test / npm test	仅显示失败，通过的测试折叠为计数
ruff check	按规则和文件分组
pytest	仅显示失败，精简 traceback
go test	解析 NDJSON，仅显示失败
docker ps	仅保留关键字段

节省是如何计算的

RTK 为你的智能体削减多达 90% 的 bash 输出。这正是 RTK 所测量的指标，它与「账单降低 90%」不是一回事。

bash 输出只是输入 token 的来源之一，此外还有你的提示词、系统提示词和对话历史。而输入 token 本身也只是账单的一部分，账单还包含输出 token。削减效果在每一步都会被稀释。

RTK 报告的 token 数量按 字节数 / 4 估算：RTK 不内置分词器，因此百分比是可靠的，但 token 绝对数值只是近似值。

完整说明：RTK 的节省是如何计算的

安装

Homebrew（推荐）

brew install rtk

winget（Windows）

Windows 上最简单的安装方式 — 一条命令，无需配置 PATH：

winget install rtk-ai.rtk

快速安装（Linux/macOS）

curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

Cargo

cargo install --git https://github.com/rtk-ai/rtk rtk

Apache-2.0 版本（仅开源，允许商业使用）

同一个 rtk 二进制文件，构建时不包含 BUSL-1.1 压缩引擎：钩子重写系统和所有命令过滤器，仅遵循 Apache-2.0。

curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | RTK_EDITION=oss sh
brew install rtk-ai/tap/rtk-oss
cargo install --git https://github.com/rtk-ai/rtk rtk --no-default-features

验证

rtk --version   # 应显示 "rtk 0.27.x"
rtk gain        # 应显示 token 节省统计

快速开始

# 1. 为对应的 AI 工具安装 hook
rtk init --global               # Claude Code（默认）
rtk init --agent trae           # Trae（项目级）
rtk init --global --agent trae  # Trae（全局）

# 2. 重启相应的 AI 工具，然后测试
git status  # 自动重写为 rtk git status

工作原理

  没有 rtk：                                      使用 rtk：

  Claude  --git status-->  shell  -->  git         Claude  --git status-->  RTK  -->  git
    ^                                   |            ^                      |          |
    |        ~2,000 tokens（原始）       |            |   ~200 tokens        | 过滤     |
    +-----------------------------------+            +------- （已过滤）-----+----------+

四种策略：

1. 智能过滤 - 去除噪音（注释、空白、样板代码）
2. 分组 - 聚合相似项（按目录分文件，按类型分错误）
3. 截断 - 保留相关上下文，删除冗余
4. 去重 - 合并重复日志行并计数

命令

下列百分比是 bash 输出字节数的削减比例，由 RTK 的 字节数 / 4 估算器测得。参见节省是如何计算的。

文件

rtk ls .                        # 优化的目录树
rtk read file.rs                # 智能文件读取
rtk find "*.rs" .               # 紧凑的查找结果
rtk grep "pattern" .            # 按文件分组的搜索结果

Git

rtk git status                  # 紧凑状态
rtk git log -n 10               # 单行提交
rtk git diff                    # 精简 diff
rtk git push                    # -> "ok main"

测试

rtk jest                        # Jest 紧凑输出
rtk vitest                      # Vitest 紧凑输出
rtk pytest                      # Python 测试（-90%）
rtk go test                     # Go 测试（-90%）
rtk test <cmd> [args...]        # 仅显示失败（-90%），直接执行 argv

构建 & 检查

rtk lint                        # ESLint 按规则分组
rtk tsc                         # TypeScript 错误分组
rtk cargo build                 # Cargo 构建（-80%）
rtk ruff check                  # Python lint（-80%）

容器

rtk docker ps                   # 紧凑容器列表
rtk docker logs <container>     # 去重日志
rtk kubectl pods                # 紧凑 Pod 列表

分析

rtk gain                        # 节省统计
rtk gain --graph                # ASCII 图表（30 天）
rtk discover                    # 发现遗漏的节省机会

文档

• TROUBLESHOOTING.md - 解决常见问题
• INSTALL.md - 详细安装指南
• ARCHITECTURE.md - 技术架构

贡献

欢迎贡献！请在 GitHub 上提交 issue 或 PR。

加入 Discord 社区。

许可证

Apache 2.0 许可证 - 详见 LICENSE。

engine/ and proxy/ are licensed BUSL-1.1 — see their LICENSE files.

免责声明

详见 DISCLAIMER.md。