diff --git a/AGENTS.md b/AGENTS.md index c76bd25..4468b19 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ the tiers in @references/commands.md. ## The one rule: compress noise, preserve signal Use `rtk ` when output is **large, repetitive, low-stakes** — skim, not -study: `rtk ls`, `rtk tree`, `rtk git status`, `rtk git log`, `rtk docker ps`, +study: `rtk ls`, `rtk git status`, `rtk git log`, `rtk docker ps`, `rtk pip list`, and big test/build runs (`rtk cargo test`, or `rtk err ` — RTK keeps the failures and drops the green). @@ -33,15 +33,15 @@ When unsure, start raw. Lean context comes from cutting *noise*, not *signal*. ## Never default to lossy modes -Plain `rtk ` is near-lossless (keeps errors, diffs, stack traces, exit -codes). `-u` / `--ultra-compact`, `rtk read … -l aggressive`, and `rtk smart` +Plain `rtk ` keeps the signal — errors, diffs, stack traces, exit codes — +and strips only noise. `-u` / `--ultra-compact`, `rtk read … -l aggressive`, and `rtk smart` (2-line summary) are **lossy** — opt-in only for skimming something huge and unimportant, never your default. ## If a compressed view isn't enough -RTK retains the full unfiltered output, so you don't have to guess and you -shouldn't thrash: re-run that one command raw (or `rtk proxy `) to see +On failure, RTK's tee fallback already kept the full output. Otherwise don't +guess or thrash: re-run that one command raw (or `rtk proxy `) to see everything, then move on. One deliberate re-run is fine; blind repeated re-runs erase the savings. diff --git a/README.md b/README.md index fa175c1..4c43541 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,10 @@ learns your coding style. Command Code CLI reads `~/.commandcode/AGENTS.md` and injects it into the system prompt for every session. This repository provides that AGENTS.md file (plus a loadable skill), teaching Command Code to route **noisy** shell output through -`rtk` while keeping **full fidelity** for output it needs exactly. The fastest -setup is RTK's auto-rewrite hook (`rtk init -g`), which rewrites commands for you -so nothing has to be prefixed by hand. +`rtk` while keeping **full fidelity** for output it needs exactly. `rtk init` +doesn't target Command Code yet, so the working default is this memory file — the +agent prefixes commands itself; register a Command Code `PreToolUse` hook and RTK +can rewrite them for you automatically. ``` Without RTK: With RTK: @@ -40,14 +41,15 @@ command. Two design choices keep it net-positive: -- **Lossless by default.** Plain `rtk ` preserves errors, stack traces, diff - hunks, and exit codes; the lossy modes (`-u` / `--ultra-compact`, `-l - aggressive`, `rtk smart`) are opt-in for skimming only — never the default. On - output it can't parse, RTK falls back to the full raw text. +- **Signal-preserving by default.** Plain `rtk ` keeps errors, stack traces, + diff hunks, and exit codes and strips only noise; the lossy modes (`-u` / + `--ultra-compact`, `-l aggressive`, `rtk smart`) are opt-in for skimming only — + never the default. If a command fails or RTK can't parse its output, you get the + full raw text back (tee fallback). - **Measure net, not gross.** `rtk gain` reports gross savings; the goal is *net* — savings minus any re-runs and minus the standing cost of these instructions. - `rtk gain --failures` and `rtk discover` show where RTK fits and where it - doesn't (see [references/analytics.md](references/analytics.md)). + `rtk discover` shows where RTK fits and where savings run low (see + [references/analytics.md](references/analytics.md)). This matters for quality too: every frontier model degrades as irrelevant context grows ("context rot" / "lost in the middle"), so cutting genuine noise can *help* @@ -70,10 +72,11 @@ the first and avoid the second. > enforcement, install the memory (Method 2); the skill (Method 1) is the > quickest install and is enough when you mainly want it during shell-heavy work. -> **Even better — the auto-rewrite hook.** RTK can install a `PreToolUse` hook -> (`rtk init -g`) that rewrites Bash commands to `rtk` automatically, so the agent -> never prefixes anything by hand. Pair it with the memory or skill below, which -> carry the *when-to-compress* rules. See `rtk init --help`. +> **Optional — the auto-rewrite hook.** A `PreToolUse` hook can rewrite Bash +> commands to `rtk` automatically so the agent never prefixes by hand. Note that +> RTK's `rtk init` installer doesn't target Command Code yet (`rtk init -g` wires +> up Claude Code/Copilot), so for Command Code you'd register the hook yourself. +> Until then, Method 2 below is the reliable path. See `rtk init --help`. ### Method 1: Skill (quick install, on-demand) @@ -125,7 +128,7 @@ leaves precise output alone: | Category | Command | Through RTK? | Est. savings | |---|---|---|---| -| Status / listings | `rtk git status`, `rtk ls`, `rtk tree` | 🟢 yes | ~80% | +| Status / listings | `rtk git status`, `rtk ls`, `rtk git log` | 🟢 yes | ~80% | | Logs / containers | `rtk docker ps`, `rtk log app.log` | 🟢 yes | ~80% | | Dependencies | `rtk pip list`, `rtk pnpm list` | 🟢 yes | ~70% | | Tests / build | `rtk cargo test`, `rtk err ` | 🟡 plain mode (keeps failures) | ~90% | @@ -134,7 +137,7 @@ leaves precise output alone: | Files you'll edit | native Read tool | 🔴 not RTK | — | _Savings are illustrative; actual numbers vary by command and output size. Run -`rtk gain` to measure your own — and `rtk gain --failures` to spot poor fits._ +`rtk gain` to measure your own — and `rtk discover` to spot poor fits._ See [references/commands.md](references/commands.md) for the full tiered list and [references/analytics.md](references/analytics.md) for measuring net savings. @@ -148,8 +151,8 @@ rtk gain --graph # Visual savings chart After running a few commands through Command Code, `rtk gain` will show the accumulated savings. Track **net** savings, not just the headline number: -`rtk gain --failures` lists commands RTK had to pass through raw (poor fits), and -`rtk discover` finds new high-value targets. See +`rtk discover` finds new high-value targets and low-savings outliers, and RTK's +tee fallback keeps full output whenever a command fails. See [references/analytics.md](references/analytics.md). ## Files diff --git a/SKILL.md b/SKILL.md index ef86ab1..2e3e624 100644 --- a/SKILL.md +++ b/SKILL.md @@ -39,21 +39,23 @@ the winning side. ## Install — two ways -### 1. Auto-rewrite hook (recommended) +### 1. Auto-rewrite hook (best where supported) -Let a `PreToolUse` hook rewrite Bash commands to their `rtk` equivalents -automatically, so you never prefix by hand and nothing gets forgotten. RTK ships -this for natively-supported agents: +A `PreToolUse` hook rewrites Bash commands to their `rtk` equivalents +automatically, so you never prefix by hand and nothing gets forgotten: ```bash rtk init -g # installs the PreToolUse rewrite hook, then restart the agent ``` -RTK natively targets Claude Code, Copilot, Cursor, Gemini, Cline, and more. -Command Code also supports `PreToolUse` hooks — register one that pipes the Bash +**Caveat for Command Code:** `rtk init`'s agent list is Claude Code, Copilot, +Cursor, Gemini, Cline, and more — it does **not** include Command Code yet, so +`rtk init -g` wires up Claude Code/Copilot, not Command Code. Command Code does +support `PreToolUse` hooks, so you can register one yourself that pipes the Bash command through RTK's rewrite (see the Command Code hooks docs and `rtk init ---help`). With a hook installed you **run normal commands**, and only need the -fidelity rules below for the cases where you want to *bypass* compression. +--help`). Until Command Code is supported upstream, Method 2 is the reliable path. +With a hook installed you **run normal commands** and only need the fidelity rules +below to *bypass* compression. ### 2. Manual prefixing (no hook) @@ -78,7 +80,7 @@ Full tiered table: [references/commands.md](references/commands.md). Use the *least* compression that still answers the question: ``` -raw / native Read → rtk (near-lossless, default) → -u / -l aggressive / rtk smart (lossy, skim-only) +raw / native Read → rtk (keeps signal, default) → -u / -l aggressive / rtk smart (lossy, skim-only) ``` Start as far left as the task needs. Escalate compression only for big, boring @@ -96,9 +98,10 @@ blindly. ## Measure net savings -`rtk gain` shows gross savings; `rtk gain --failures` shows what passed through -raw; `rtk discover` finds good new targets. Optimize **net** tokens (savings -minus re-runs), not the headline number. Full reference: +`rtk gain` shows gross savings; `rtk discover` finds good new targets (and +low-savings outliers worth dropping); on failure RTK's tee fallback keeps the +full output. Optimize **net** tokens (savings minus re-runs), not the headline +number. Full reference: [references/analytics.md](references/analytics.md). ## Prerequisite diff --git a/references/analytics.md b/references/analytics.md index 157a2a7..7f364b8 100644 --- a/references/analytics.md +++ b/references/analytics.md @@ -10,7 +10,7 @@ context. Optimize for net. | `rtk gain` | session summary: tokens saved, efficiency | | `rtk gain --graph` | 30-day savings trend | | `rtk gain --history` | per-command savings — see where RTK actually pays off | -| `rtk gain --failures` | commands RTK **couldn't parse** and passed through raw | +| `rtk gain --quota` | monthly quota savings estimate | | `rtk discover` | find *good* new opportunities (don't blanket-apply) | | `rtk session` | RTK adoption across recent sessions | | `rtk gain --all --format json` | export for dashboards (run raw if you'll parse it) | @@ -18,9 +18,10 @@ context. Optimize for net. ## Reading the signal - **High `--history` savings on noisy commands** → working as intended; keep going. -- **Entries in `--failures`** → RTK fell back to raw output for those, so they - aren't saving — and may be a poor fit (structured or edge-case commands). Run - them raw and stop wrapping them. +- **Low or zero savings on a command** (visible in `--history`, or surfaced by + `rtk discover`) → it's a poor fit; run it raw and stop wrapping it. And when a + command *fails*, RTK's tee fallback (`[tee] mode = "failures"`) has already + saved the full output — so you never lose error detail on the cases that matter. - **You re-ran a command raw right after its `rtk` version** → that pair was a net *loss*. Note the command type and stop compressing it. - **`rtk discover`** surfaces high-volume, noisy commands worth wrapping — a far diff --git a/references/commands.md b/references/commands.md index 37480b4..c65c9fc 100644 --- a/references/commands.md +++ b/references/commands.md @@ -15,7 +15,7 @@ skimming something huge and unimportant. ## 🟢 Compress freely (skim-only output) | Instead of | Use | Why it's safe | |---|---|---| -| `ls -la`, `tree` | `rtk ls`, `rtk tree` | listings dedup/group cleanly | +| `ls -la` | `rtk ls` | listings dedup/group cleanly | | `git status`, `git log -n 20` | `rtk git status`, `rtk git log -n 20` | already summaries | | `docker ps`, `docker images` | `rtk docker ps`, `rtk docker images` | tabular, repetitive | | `docker logs `, `kubectl logs

` | `rtk docker logs `, `rtk kubectl logs

` | dedups repeated lines | @@ -38,7 +38,7 @@ the `file:line` you need, which forces a re-run that costs more than it saved. | Situation | Do this | Why | |---|---|---| | A diff/patch you'll apply | `git diff`, `git show` **raw** | exact bytes and line numbers matter | -| Output you'll parse (JSON, `--format`) | run raw; `rtk json file --keys-only` only to *explore* structure | compression can corrupt structure | +| Output you'll parse (JSON, `--format`) | run raw; use `rtk json file` only to *explore* structure | compression can corrupt structure | | Small output (≲30 lines) | run raw | nothing to save, real risk | | Secrets / credentials / exact config | run raw | never reason about a lossy view | | A file you'll **edit** | native Read tool | lossless + line numbers; bypasses RTK anyway | @@ -47,7 +47,7 @@ the `file:line` you need, which forces a re-run that costs more than it saved. ## Analytics Measuring real savings — and spotting bad fits before they cost you — lives in -[analytics.md](analytics.md): `rtk gain`, `rtk gain --failures`, `rtk discover`. +[analytics.md](analytics.md): `rtk gain`, `rtk discover`, and the tee fallback. > RTK supports 100+ commands. Run `rtk --help` for the full set; the tiers above > are the decision rule, not an exhaustive list. When a command isn't listed,