ashlr

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:

npm install -g ashlr-plugin
ashlr-plugin tools --json
ashlr-plugin stats --json

Claude Code plugin:

curl -fsSL https://plugin.ashlr.ai/install.sh | bash

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.
InstallCodex, Claude Code, Cursor, Goose.
QuickstartRun your first compacted read in 60 seconds.
PermissionsHook modes, redirect vs nudge, opt-outs.
CLI referenceEvery 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__readCompact head and tail or an AST summary.
ashlr__grepGenome-aware search with a ripgrep fallback.
ashlr__editDiff-only edits. Full file never re-sent.
ashlr__bashAuto-summarized stdout for verbose commands.
ashlr__sql · ashlr__http · ashlr__diff · ashlr__logs · ashlr__prPlus 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

GenomeThe on-disk knowledge graph that powers grep RAG.
snipCompactHow head+tail trimming preserves recall while cutting tokens.
Env varsAll ASHLR_* environment variables with defaults.
Status lineWhat every glyph in the live ledger means.
Savings mathHow tokensSaved is computed and why every value is reproducible.

Pro / Team

PricingFree / Pro / Team feature matrix.
Cloud genomeE2E-encrypted shared knowledge across machines and teammates.
Hosted summarizationServer-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).

PhantomThe engineering agent workbench: phm CLI, JSON interface, MCP gateway.
Phantom SecretsAgents use API keys through phm_ placeholders without seeing them.
LocusIdentity pinning for CLI commands, MCP tools and agent sessions.
LexiconA personal voice lexicon for names speech-to-text gets wrong.
Ashlr StackService setup from the terminal or an agent.
Ashlr MDDesktop 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.

On this page