Agents

Every host rtok agents install <host> configures, per app, with what rtok writes into it and which rtok plugins then reach that app.

• Hooks, MCP, Proxy, Plugin are the four modules an install can carry. yes is written by a plain install; a flag (--proxy, --yes) means the module is written only with that flag; — means the host has no way to carry it. The host README (linked from the Host column) gives the reason for every —.
• MCP is the rtok entry in the app's own config file (D33): install and update always write it, only remove takes it out, and a plugin never stands in for it. The entry runs rtok mcp --host <id> (the host's id in this table), so the MCP process knows its host; agents update adds --host to an entry an older rtok wrote without it, and remove still takes either form out.
• Plugin is a directory from plugins/<host>/ that rtok links into the host (Cursor and ZCode: the hooks; OpenCode and pi: the bash call path). Where the app would list a plugin's server next to the config entry (Claude Code and Desktop, Cursor, Copilot, Codex, VS Code, ZCode, Kimi, Grok), the rtok plugin ships no MCP server; Gemini's extension keeps one, which the settings.json entry overrides.
• rtok plugins reached lists every catalogue plugin with at least one surface (hook, bash call path, MCP, proxy) a module above can carry. (off) plugins are disabled by default and need [plugins.<id>] enabled = true.

Check what is installed on this machine with rtok agents list; rtok doctor reports the same modules, and warns when an installed host's config has no rtok MCP entry, or a stale one, naming the rtok agents install <host> (with --cli or --desktop) that writes it.

rtok doctor also reports broken hooks, duplicate hooks and duplicate MCP entries in the hosts' config files. rtok doctor --fix cleans them up. In a terminal it opens a checklist of every removable item: a number toggles it, k N keeps copy N of a duplicate instead, d shows the diff of each file, y asks for the last confirmation and writes (after a backup in _backup/), q leaves. Items in a shared project file start unselected, since the change reaches your teammates. Without a terminal, --fix prints the diffs and writes nothing; --fix --yes writes the default selection without asking; --only broken-hooks|duplicate-hooks|duplicate-mcp (repeatable) limits it and --agent <host> limits it to one host. The kept copy of a duplicate, a plugin's own files and rtok's own entries are never removed, and every byte outside the removed entries stays as it was. The rtok entry that install writes is always the kept copy. The same rtok name in another scope and a plugin's copy (Gemini's extension) are listed as information only, because the host merges or shadows them (for the plugin copy, rtok agents update <host> brings the plugin up to date); only a hand-written copy under another name that also runs rtok mcp, such as rtok-mcp, is offered for removal. The Doctor tab of rtok tui has the same checklist: f opens it, Space toggles an entry, k keeps this copy, Enter shows the confirmation and y writes; any other key declines.

After an rtok upgrade, rtok agents update brings every installed host up to date; for Claude Code it decides by plugin version — see Plugin versions and updates.

The table is generated from the host code (src/agents/<host>/mod.rs and the plugin catalogue) by tests/agents_doc.rs, which fails when it is stale. After changing a host, adding one, or changing a plugin's surfaces, regenerate it:

RTOK_BLESS=1 mise exec -- cargo test --test agents_doc

The rtok plugins reached column is computed from declared surfaces: a plugin is listed when the host supports the surface the plugin answers on. It does not prove that every event the plugin needs is registered on that host — auditing that per host is task T70.7 in plan.md.

Claude Code also gets a PreToolUse hook on Skill (T62.1). It is inert until [plugins.guard] skills = true; then a SKILL.md over skill_max_bytes is archived and the call is denied with the file's heading map and an rtok expand <id> pointer. A skill digested this way does not apply its frontmatter, so skills carrying allowed-tools, model, context or agent always load whole.

What a host plugin reaches that rtok's own surfaces do not

rtok has three surfaces of its own (hook, MCP, proxy), and each has a hard edge:

• A PostToolUse hook cannot modify a tool result, only add context. On Claude Code that is why only Bash shrinks — it is rewritten to rtok run before it executes. A Read, Grep or foreign MCP result enters context whole.
• The archive live zone runs inside rtok proxy. A host with no base-URL setting never shrinks an old tool result, however long the session runs.
• A host with no hook events reaches no hook plugin, so inject has no way in. guard reaches pi and OpenCode through rtok guard check on the linked plugin (T70.5).

A host plugin — the directory under plugins/<host>/ that rtok agents install <host> links — sits inside the host process and is not bound by those edges. Where a host's plugin API is richer than its hook API, the plugin is the only path to the capability. Documented API positions, surveyed 2026-09-18 (research.md §15):

Two consequences drive the open work in plan.md: on pi the whole archive live zone can run without a proxy (T70.2), and MCP results a host launched itself can be shortened where the plugin API allows it (T70.4) — neither is reachable from rtok mcp, rtok hook or rtok proxy. Claude Code's and ZCode's plugins carry the same hook events as their settings files, no richer API; Codex, Claude Desktop, Windsurf, Zed, Kimi and Copilot have no plugin directory. For all of them the proxy stays the only path.

Every one of those tasks begins by re-verifying the host's API against its current documentation: the table above is a survey of vendor docs, not a measurement.

Which hosts rtok agents usage reads

rtok agents usage --source logs totals tokens from each host's own session files (the directories are [agents.usage.dirs] in docs/config.md, and research.md section 30 cites the source of every format).

An unsupported host whose directory has files is named under skipped in the report, so a missing agent is visible instead of silently counted as zero.

Outdated plugins

rtok agents outdated lists only hosts where rtok's plugin is installed and its version is older than the running rtok binary (SemVer precedence; build metadata on the same release is still current). Hosts that are up to date, not installed, or newer are omitted. rtok agents update --check prints the same report.

rtok agents outdated              # every host in the table above
rtok agents outdated claude,cursor
rtok agents outdated --json
rtok agents outdated --exit-code  # exit 10 when anything is outdated (CI)

When every installed plugin matches the binary, the command prints how many are installed and the rtok version; when none are installed it prints no rtok plugins installed. The check is local only (receipt, version file, host records) — no network and no host CLI. More in Plugin versions: Listing outdated plugins.

Junk

rtok agents junk list shows, for rtok and every installed host, its folders with their sizes, the junk kinds inside them and how much rtok agents junk clear would free. clear is a dry run until --yes.

Both commands print the items behind the totals, so you can check the exact set before deleting. Each item is one line: its path (a link in a terminal that supports them, with ~ for your home), its size, when it was last used (the newest file in it, for example 3 weeks ago (2026-09-09 14:02)), why it is junk, and, when it will not be cleared, why not (review kind: add --include review, agent running).

• --items N|all sets how many items each kind lists (default 10, then +N more (size)); --items 0 prints the totals only.
• --sort size|last-used|path orders the items inside each kind: largest first (default), longest unused first, or by path. An item whose time cannot be read counts as recent and sorts last. Agents themselves always come by the space clear frees, largest first.
• --min-size SIZE (a number with B, KB, MB, GB or TB) hides smaller items. On clear it also limits the plan, so what the dry run lists is what --yes removes.
• --json always carries every item: path, size_bytes, last_used (Unix seconds or null), reason, will_clear and, when it is not cleared, skip_reason.

rtok doctor adds a junk line with the space clear would free by default, and points at rtok agents junk list when that is over a gigabyte. The Hosts page of rtok web and rtok tui shows the same list.

On the Hosts page of rtok web the list is a junk card: per agent and kind the items and sizes, and the Freed by clear and Freed with --include review lines. Its Clear safe junk button runs the dry run of clear for every agent's safe kinds (never review, explicit or never kinds, and never the trash), lists what it would remove, and deletes nothing until you press Confirm. Only the items you were shown are removed, each one checked again just before it goes, so a running agent's files, a changed folder, a symlink or a protected file stay and are reported. On the Hosts tab of rtok tui, c shows the same dry run and y removes what it listed; any other key declines and leaves every file as it was. The result ends with Freed X of Y planned.