Quickstart

After installing, open Codex or Claude Code in any project directory. In Cursor or Goose, make sure the Ashlr MCP server is registered first.

Step 1 — run a host check

In Codex:

bun run scripts/cli.ts codex-doctor --json

In Claude Code:

/ashlr-tour

Claude's tour walks through the tools on your actual project files. Codex users can use ashlr codex-start --json for the same workflow nudge.

Step 2 — call ashlr__read directly

Ask your agent to read a large file using the efficient tool:

"Use ashlr__read to read src/index.ts"

The agent will call ashlr__read. The response includes:

• File head and tail, with the middle snipped if over 2 KB
• A confidence badge ([A], [B], [C], or [?]) showing summarization quality
• Tokens saved vs the raw read, reported in the tool output

Step 3 — check the ledger

In Codex:

ashlr stats --json

In Claude Code:

/ashlr-savings

Both print session and lifetime token accounting. You should see entries for the calls you just made.

Step 4 — approve all tools in Claude Code

To stop Claude Code prompting for permission on each ashlr tool call:

/ashlr-allow

This writes the tool allowlist to .claude/settings.json. Restart or reload plugins after running.

Codex uses nudge-first hooks by default; Cursor and Goose use their host MCP permission model.

Next steps

• Permissions — understand what /ashlr-allow does under the hood
• MCP tools — full reference for every tool
• Genome — how the project genome index is built and used