GitHub Browse tools

Getting started with rtok

From docs/getting-started.md at cc732c3 View on GitHub

rtok reduces the context AI coding agents must carry. One Rust binary, three surfaces: Claude Code hooks, an MCP server, and an API proxy. Each reduction is measured; shortened payloads stay retrievable by id.

Install

macOS (Apple silicon) and Linux x86-64 have prebuilt binaries. The installer is POSIX sh and puts rtok (plus rtok-update) in ~/.cargo/bin.

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/pyrlyn/rtok/releases/latest/download/rtok-installer.sh | sh

Or with ketch, from the same release archives:

ketch install pyrlyn/rtok

Hooks try the fast rtok-hook client first. When a package manager links only rtok onto PATH, rtok mcp, rtok hook --serve and rtok agents install link the rtok-hook beside it into the same PATH directory (unix, best effort; an existing foreign file is left alone).

From source (toolchain pinned in mise.toml):

git clone https://github.com/pyrlyn/rtok && cd rtok
mise install
mise exec -- cargo install --path .
rtok --version

First run

rtok config init      # writes ~/.rtok/config.toml
rtok plugins          # id, enabled, surfaces
rtok doctor           # inspect hooks, MCP servers, proxy chain

rtok doctor is worth running before you install anything: it prices the hooks and MCP servers you already have, including description tokens re-sent on every turn.

A subcommand whose plugin was compiled out prints not implemented and exits 0, so a stripped or half-installed rtok never blocks the host agent.

Wire into Claude Code

rtok agents install claude --dry-run
rtok agents install claude
rtok agents uninstall claude

--dry-run prints the hook entries and touches nothing. Install backs up every file it writes. See the root README for other hosts (cursor, codex, opencode, …).

Four invariants

  1. Fail open. A hook exits 0 in ≤ 10 ms even on error, with unmodified input.
  2. Lossless by default. Anything shortened is retrievable via rtok expand <id>.
  3. A saving that is not a Measurement row does not exist.
  4. Injected context stays under budget and byte-stable, so it never busts the prompt cache.

Where things live

~/.rtok/config.toml     configuration (`RTOK_HOME` overrides the directory)
~/.rtok/rtok.db         SQLite — measurements, archive index, memory
~/.rtok/archive/        raw payloads, addressed by expand id
<git root>/.rtok.toml   optional per-project overrides

Caveats

  • Token counts from rtok stats are estimates (see src/tokens.rs) plus real usage rows from the proxy. Only the proxy rows are the actual bill.
  • The committed A/B bench has only been run offline, so it reports zeros for both configurations. Rerun it against live traffic before adopting a configuration on its word.

Next