# fewtok Token-compression proxy for Claude Code — paths, boilerplate, file-read dedup. Sits between your AI coding tool and the Anthropic API. Transparently replaces long repeated strings (file paths, boilerplate phrases) with short `§` aliases, tracks the savings, and reports them in a `gain` command modelled after RTK. **Typical savings:** 20–30% on real-world Claude Code sessions. --- ## Requirements - [Bun](https://bun.sh) ≥ 1.1.0 ## Install (from source) ```bash git clone https://github.com/alexcodeplace/fewtok cd fewtok bun install bun link ``` ## Quick start ```bash fewtok init # bootstrap dirs, pin a port fewtok install claude # wire Claude Code to the proxy fewtok start # start proxy in background cld # drop-in claude launcher — proxy auto-starts if down fewtok gain # see token + dollar savings ``` --- ## `cld` — drop-in Claude Code launcher `cld` replaces `claude` in your daily workflow. It auto-starts the proxy if it isn't running, then launches `claude` with `ANTHROPIC_BASE_URL` pointed at the proxy. ```bash cld # same as claude cld --yolo # maps --yolo → --dangerously-skip-permissions ``` Port is read from `~/.fewtok/state/proxy.port`. --- ## Commands ### `fewtok init` Bootstrap fewtok for the current session and project. - Creates `~/.fewtok/` (global dirs: config, registry, stats, cache, logs) - Creates `.fewtok/` in the current directory (project-level dicts) - Pins a free port to `~/.fewtok/config.json` - Prints the `ANTHROPIC_BASE_URL` export line for manual use Run once globally; re-run per project to initialise project-level dicts. --- ### `fewtok install [--all]` Wire fewtok into your AI coding tool. Requires `fewtok init` first. ```bash fewtok install claude # Claude Code fewtok install opencode # OpenCode fewtok install cline # Cline (VS Code extension) fewtok install aider # Aider fewtok install --all # all of the above ``` | Tool | What it writes | |------|----------------| | `claude` | Appends `export ANTHROPIC_BASE_URL=http://127.0.0.1:` to your shell rc | | `opencode` | Writes `baseURL` into the OpenCode config | | `cline` | Writes `anthropicBaseUrl` into `~/.config/cline/config.json` | | `aider` | Writes `--openai-api-base` into the Aider config | --- ### `fewtok start` / `fewtok stop` ```bash fewtok start # start in background (default) fewtok start --foreground # start in foreground, logs to stdout fewtok start --port 7878 # override port for this run fewtok stop # stop the background proxy ``` --- ### `fewtok gain` Show token savings report. ```bash fewtok gain # full report, all-time fewtok gain --today # today only fewtok gain --since 7d # last 7 days (accepts: 24h, 7d, 30d) fewtok gain --project-dir ./myapp # filter by project fewtok gain --model claude-opus-4-7 # override model for dollar conversion fewtok gain --top 10 # show top 10 aliases only fewtok gain --format json # machine-readable JSON fewtok gain --no-color # strip ANSI colours fewtok gain --stats-dir ~/.fewtok # override stats.db path (debug) ``` **Report sections:** - **North star** — total saved (tokens + USD), today highlight - **By-layer** — sparkbar breakdown per compression layer - **By-project** — per-project savings - **Volume** — requests, Anthropic cache hit %, avg / p99 latency - **Top aliases** — most-used `§` codes and their savings **JSON shape (`--format json`):** ```json { "window": "all-time", "northStar": { "savedUsd": 12.47, "savedTokens": 3420000, "todayUsd": 0.83, "todayTokens": 421000 }, "layers": [...], "projects": [...], "volume": { "requests": 142, "cacheHitPct": 0.713, "avgLatencyMs": 218, "p99LatencyMs": 894, "anthropicCacheTokens": 9800000 }, "topAliases": [...] } ``` --- ### `fewtok doctor` Health check: proxy running status, port, config validity, stats DB. --- ### `fewtok dict` Manage compression aliases. ```bash fewtok dict list fewtok dict add --code §R --expansion /home/user/Projects/myapp fewtok dict rm §R fewtok dict gc # remove aliases with 0 uses ``` --- ### `fewtok discover` Scan past sessions and suggest high-value aliases. Auto-detects repeated paths and boilerplate phrases above the savings threshold. --- ## Configuration `~/.fewtok/config.json`: ```json { "port": 7878, "hints": { "enabled": true } } ``` | Key | Default | Description | |-----|---------|-------------| | `port` | auto | Proxy listen port. Set by `fewtok init`. | | `hints.enabled` | `true` | Auto-manage alias hint block in CLAUDE.md. | Disable hint injection: `fewtok config set hints.enabled false` --- ## Files on disk ``` ~/.fewtok/ config.json # global config (port, settings) registry.db # alias registry (all codes ever assigned) stats.db # token savings per request (SQLite) state/ proxy.pid proxy.port last_scan_.ts cache/ reads/ # per-session file-read dedup logs/ proxy-YYYY-MM-DD.log learn-YYYY-MM-DD.log global/ paths.json # global path aliases macros.json # global macro aliases /.fewtok/ config.json paths.json # project path aliases macros.json # project macro aliases ``` Both `~/.fewtok/` and `/.fewtok/` are gitignored. --- ## How it works 1. `ANTHROPIC_BASE_URL=http://127.0.0.1:` routes Claude Code traffic through fewtok (officially supported env var). 2. Proxy receives the full JSON request (messages, system prompt, tools) on every turn. 3. **Path codec** replaces long repeated paths with `§` aliases (`§R` = `/home/user/Projects/myapp`). 4. **Macro codec** collapses repeated boilerplate phrases into short codes. 5. Compressed request is forwarded to `api.anthropic.com`. 6. Response is expanded back before it reaches Claude Code — fully transparent. 7. Every request is logged to `~/.fewtok/stats.db`. CLAUDE.md gets an auto-managed block that teaches the model the active alias set — so the model can emit `§R` directly, compressing its own output. --- ## RTK Integration fewtok transparently routes Bash commands through [RTK](https://github.com/reachingforthejack/rtk) when RTK is installed. No model or user action required. **Two complementary compression layers:** - **RTK** (CLI layer) — compresses command stdout before it reaches the API - **fewtok** (API layer) — compresses paths, macros, repeated file reads in the request body Together they achieve 60–90% savings on development operations. **Supported commands:** `git`, `gh`, `pnpm`, `npm`, `npx`, `yarn`, `find`, `grep`, `ls`, `tree`, `tsc`, `jest`, `vitest`, `playwright`, `lint`, `prettier`, `next`, `prisma`, `dotnet`, `cargo`, `curl`, `wget`, `docker`, `kubectl`, `psql`, `aws`, `diff`, `wc` **Limitations:** - Chained commands with `&&` only route the first segment through RTK - RTK install state is detected at proxy startup — restart the proxy after installing RTK **Setup:** ```bash cargo install rtk # install RTK (or per RTK docs) fewtok start # start fewtok — routing is automatic ``` --- ## Alias sigil — `§` fewtok uses `§` (section sign, U+00A7) as the alias prefix. - Costs **2 tokens flat** regardless of suffix length. - Low collision risk vs. common ASCII characters. - Example: `§R/deals/DealDetail.tsx` (12 tok) vs. `/home/user/Projects/multideal/apps/web/src/deals/DealDetail.tsx` (27 tok) — **55% cut per occurrence**. --- ## Supported models (dollar conversion) | Model | Input | Output | Cached input | |-------|-------|--------|--------------| | `claude-opus-4-7` | $15 / 1M tok | $75 / 1M tok | $1.50 / 1M tok | | `claude-sonnet-4-6` | $3 / 1M tok | $15 / 1M tok | $0.30 / 1M tok | | `claude-haiku-4-5-20251001` | $0.80 / 1M tok | $4 / 1M tok | $0.08 / 1M tok | Default model for dollar conversion: `claude-sonnet-4-6`. Override with `--model`. --- ## License MIT