ashlr docs
Open-source token ledger for Codex, Claude Code, Cursor, and Goose. 54 MCP tools, Codex skills, 39 slash commands, MIT-licensed, opt-in telemetry.
ashlr is the open-source token ledger for AI coding tools. Agents install it, call the CLI with --json, and register the MCP server. Humans use the same path.
Per-call savings: reads about 75% smaller, greps about 27% smaller (not a whole session). The same 2026-10-17 run's per-repo means were about 60% on vercel/ai, about 63% on pandas, and about 55% on tokio. Reproduce with the benchmark script. (methodology)
MIT-licensed. Telemetry is off by default and explicit opt-in only. Codex gets a plugin manifest, MCP config, workflow skills, and nudge-first hooks. Claude Code gets slash commands and a status line. Cursor and Goose register the same MCP router.
Agent index: llms.txt. Runnable reference: llms-full.txt.
Install
One command for the CLI and ashlr-mcp:
Claude Code plugin:
Codex plugin commands, and the Cursor and Goose files, are on the install page. MCP snippets for Claude Code, Cursor, and Codex are in the repository llms-full.txt.
Documentation map
Start here
| What is ashlr? | The three-line pitch and what's included. |
| Install | Codex, Claude Code, Cursor, Goose. |
| Quickstart | Run your first compacted read in 60 seconds. |
| Permissions | Hook modes, redirect vs nudge, opt-outs. |
| CLI reference | Every ashlr-plugin subcommand and its JSON output. |
MCP tools (54)
The drop-in replacements that do the actual token-saving. See the tools index for the full catalog.
ashlr__read | Compact head and tail or an AST summary. |
ashlr__grep | Genome-aware search with a ripgrep fallback. |
ashlr__edit | Diff-only edits. Full file never re-sent. |
ashlr__bash | Auto-summarized stdout for verbose commands. |
ashlr__sql · ashlr__http · ashlr__diff · ashlr__logs · ashlr__pr | Plus 30+ more. |
See the capabilities matrix for the full machine-readable tool reference.
Commands + Skills
Codex ships workflow skills for doctor checks, compact read/search habits, genome refresh, savings review, and parallel exploration. Claude Code ships 39 slash commands; type /ashlr- to discover them. See skills for the full list of dashboards, demos, and diagnostics.
Concepts
| Genome | The on-disk knowledge graph that powers grep RAG. |
| snipCompact | How head+tail trimming preserves recall while cutting tokens. |
| Env vars | All ASHLR_* environment variables with defaults. |
| Status line | What every glyph in the live ledger means. |
| Savings math | How tokensSaved is computed and why every value is reproducible. |
Pro / Team
| Pricing | Free / Pro / Team feature matrix. |
| Cloud genome | E2E-encrypted shared knowledge across machines and teammates. |
| Hosted summarization | Server-side LLM compaction for very large reads. |
Part of the Ashlr ecosystem
ashlr is the efficiency layer of the Ashlr ecosystem. Phantom and its sibling repos form an autonomous, code-first, agent-native software factory: agents do the engineering, the human sits as a passive board member, and the goal is open source RSI (recursive self-improvement).
| Phantom | The engineering agent workbench: phm CLI, JSON interface, MCP gateway. |
| Phantom Secrets | Agents use API keys through phm_ placeholders without seeing them. |
| Locus | Identity pinning for CLI commands, MCP tools and agent sessions. |
| Lexicon | A personal voice lexicon for names speech-to-text gets wrong. |
| Ashlr Stack | Service setup from the terminal or an agent. |
| Ashlr MD | Desktop Markdown app with on-device AI. |
More on how the pieces fit, including the --ashlr-handshake discovery contract, is in What is ashlr?.
Contributing
ashlr is MIT-licensed and lives at github.com/ashlrai/ashlr-plugin. PRs welcome. Read the contributing guide first.
Have feedback on the docs? Open an issue on GitHub. Every page has an "Edit on GitHub" link in the corner.