GitHub Browse tools

rtok documentation

Less context for your agent, every saving on record.

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.

Start with Getting started About rtok

45 pages from pyrlyn/rtok/docs at cc732c3, in development

  1. Install 
    curl --proto '=https' --tlsv1.2 -LsSf https://github.com/pyrlyn/rtok/releases/latest/download/rtok-installer.sh | sh
  2. Configure 
    rtok config init
  3. Inspect 
    rtok doctor
  4. Wire in 
    rtok agents install claude --dry-run

How it works

From install to first result.

  1. Install one binary

    Prebuilt binaries for macOS (Apple silicon) and Linux x86-64. The installer puts rtok and rtok-update in ~/.cargo/bin; ketch install pyrlyn/rtok works too.

    ketch install pyrlyn/rtok

  2. Price what you already run

    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.

    rtok doctor

  3. Wire it into your agent

    --dry-run prints the hook entries and touches nothing. Install backs up every file it writes, and uninstall takes it out again.

    rtok agents install claude

  4. Expand anything that was cut

    Lossless by default: anything shortened is retrievable by id, and a saving that is not a Measurement row does not exist.

    rtok expand <id>

Four invariants

The rules every surface keeps.

  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.
rtok config init      # writes ~/.rtok/config.toml
rtok plugins          # id, enabled, surfaces
rtok doctor           # inspect hooks, MCP servers, proxy chain
First run, from Getting started

Paths into the docs

Pick where to go next.

Where things live

Everything rtok keeps, in one place.

PathWhat it holds
~/.rtok/config.tomlConfiguration (RTOK_HOME overrides the directory)
~/.rtok/rtok.dbSQLite — measurements, archive index, memory
~/.rtok/archive/Raw payloads, addressed by expand id
<git root>/.rtok.tomlOptional per-project overrides

Questions the docs answer

Good to know.

Does rtok break the prompt cache?

No — measured, not promised. The Prompt cache page reports hit=97.5% from rtok stats on the maintainer's machine (2026-09-18) and zero recorded prompt-cache busts in rtok report. Injection is byte-stable, rewrites stay outside the conversation's working edge, and hooks touch each result once.

What happens if a plugin was compiled out?

The subcommand prints not implemented and exits 0, so a stripped or half-installed rtok never blocks the host agent.

Which agents can it wire into?

rtok agents install <host> configures Claude Code and other hosts such as cursor, codex and opencode. The Agents page lists, per host, what an install writes and which rtok plugins then reach that app.

Where did a setting come from?

Every CLI flag is a config key in ~/.rtok/config.toml, and rtok config show --sources always tells you where a value came from.

Next steps

Read these first.

  1. Getting started 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.
  2. Configuration One file, ~/.rtok/config.toml, holds every setting rtok has. Every CLI flag is a config key, so anything you can pass on the command line you can also make permanent, and rtok config show --sources always tells you…
  3. Agents Every host rtok agents install <host> configures, per app, with what rtok writes into it and which rtok plugins then reach that app.