ashlr-plugin

Cut Claude Code token usage by −57% on real codebases. TS −62% · Python −65% · Rust −44% — measured on vercel/ai, pandas, and tokio. (methodology)

40 MCP tools that replace Claude Code's built-in Read / Grep / Edit / Bash and friends with versions that return less without losing what matters. PreToolUse hooks redirect native tool calls automatically (ASHLR_HOOK_MODE=redirect), so existing prompts get the savings with zero retraining.

# macOS / Linux
curl -fsSL plugin.ashlr.ai/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ashlrai/ashlr-plugin/main/docs/install.ps1 | iex

Landing page: plugin.ashlr.ai · Core library: @ashlr/core-efficiency · License: MIT

Tested on: Ubuntu 22.04 · macOS 14 (Sonoma) · Windows Server 2022 · TypeScript hooks (no bash required)

---

What's new in v1.22

• Hybrid LLM summarization — Anthropic Haiku 4.5 default → ONNX offline → local LM Studio opt-in. Real summarization without your own GPU.
• Redirect mode default — PreToolUse hooks now redirect native Read / Grep / Edit / Write / MultiEdit / NotebookEdit / WebSearch / Task* to ashlr equivalents instead of just nudging.
• Privacy by default — telemetry off, explicit opt-in only.

---

Permissions — stop the prompts first

Run this once after install so Claude Code stops asking on every tool call:

/ashlr-allow

That adds ashlr MCP wildcards to permissions.allow in ~/.claude/settings.json. It is idempotent. Run /reload-plugins after changing permissions, or fully quit and restart Claude Code if reload is unavailable.

---

10-second demo

# 1. Install
curl -fsSL plugin.ashlr.ai/install.sh | bash
# Inside Claude Code:
/plugin marketplace add ashlrai/ashlr-plugin
/plugin install ashlr@ashlr-marketplace

# 2. Use — read a large file (raw would be ~8,400 tokens)
ashlr__read  { "path": "src/server.ts" }
# Returns snipCompact view: head + tail, elided middle — ~1,700 tokens

# 3. Check savings
/ashlr-savings

Session savings  ·  ashlr-plugin v1.29.0
────────────────────────────────────────
  ashlr__read      6 calls    −42,180 tok   $0.13
  ashlr__grep      3 calls    −11,040 tok   $0.03
  ashlr__edit      2 calls     −3,200 tok   $0.01
  ─────────────────────────────────────────────
  Session total               −56,420 tok   $0.17
  Lifetime total             −284,900 tok   $0.86
  7-day sparkline   ▁▂▃▃▅▆█

---

What you get

Core efficiency tools (replace built-ins with lower-token equivalents):

MCP tool	Description
ashlr__read	snipCompact + LLM summary on files > 16 KB (Anthropic Haiku 4.5 default, ONNX/local fallback). Mean −82.1% on the v1.22 bench. Line numbers preserved on code files.
ashlr__grep	Genome-aware RAG when .ashlrcode/genome/ or cloud genome exists; ripgrep fallback with LLM summary.
ashlr__edit	In-place search/replace — returns diff summary only, not the full file. Levenshtein candidates on miss.
ashlr__edit_structural	AST-aware rename (Unicode identifiers: café, π, CJK) + cross-file rename with anchorFile + maxFiles + shadowing guard + dryRun + extract-function with return-value detection (0 / 1 / N outputs). .ts/.tsx/.js/.jsx.
ashlr__multi_edit	Batch multiple search/replace edits in one call.
ashlr__savings	Live token-savings dashboard: session + lifetime + per-tool breakdown.

Shell, data, and web tools:

MCP tool	Description
ashlr__bash	Shell with auto-compression + pluggable summarizer registry (servers/_bash-summarizers-registry.ts) covering git log/git diff/git show, ls, ps, npm ls, unified test-runner output, tsc, and npm/bun/yarn/pnpm installs. Long-running commands survive timeouts via process-group SIGKILL.
ashlr__bash_start / _tail / _stop / _list	Long-running background command control plane.
ashlr__sql	SQLite + Postgres one-shot. explain and schema modes. LLM summary on 100+ row results.
ashlr__http	HTTP fetch with readable-extract (HTML), array-elide (JSON), and private-host safety.
ashlr__webfetch	Fetch + extract web pages with token budget. LLM summarization kicks in at 4 KB (web content is denser than code), 100 KB hard cap.
ashlr__logs	Tail with level filter + dedupe + LLM summary.
ashlr__diff	Adaptive git diff (stat/summary/full) with LLM summary on big diffs.
ashlr__diff_semantic	Semantic diff with meaning-aware change grouping.
ashlr__test	Structured test-runner output parser — bun/vitest/jest/pytest/go test. Compresses runner noise into one failure block per failure.

Codebase navigation:

MCP tool	Description
ashlr__tree	gitignore-aware directory tree with per-dir truncation + size/LOC modes.
ashlr__glob	gitignore-aware file glob with size/LOC metadata.
ashlr__ls	Directory listing with size metadata.
ashlr__orient	Codebase orientation: entry points, key files, dependency graph.

Genome + GitHub:

MCP tool	Description
ashlr__genome_propose / _consolidate / _status	Active genome scribe loop — keeps .ashlrcode/genome/ current as you code.
ashlr__issue / ashlr__pr	GitHub issue and PR read ops.
ashlr__issue_create / ashlr__issue_close	GitHub issue write ops. Self-approval guard + ASHLR_REQUIRE_GH_CONFIRM=1 opt-in confirmation.
ashlr__pr_comment / ashlr__pr_approve	GitHub PR write ops. pr:"current" resolves via gh pr view. No destructive ops (no merge/close/delete).
ashlr__ask	Ask a question, get a structured answer with citations.

See docs/architecture.md for the full tool registry and router layout.

---

Pro cloud

ashlr Pro connects to a hosted backend at https://api.ashlr.ai, unlocking features that require server-side state:

Feature	What it does
Cross-machine stats	Aggregate token savings across all your machines. GET /v1/stats/aggregate returns machine_count + combined lifetime totals.
Hosted summarizer	POST /v1/llm/summarize — cloud inference via xAI Grok 4.3. Falls back to your local ONNX or Anthropic key when offline.
Team genome	Encrypted genome sync across teammates. DEKs wrapped with X25519 — only key-holders can decrypt (/ashlr-genome-team-init).

Privacy: telemetry is off by default and explicit opt-in only (ASHLR_TELEMETRY=on). The sessionId is an opaque 16-char hex value per session — never your user identity — and is stored server-side as a SHA-256 hash. File paths and content are never sent. See docs/telemetry.md for the full privacy contract.

Production URL: https://api.ashlr.ai

The /ashlr-doctor command includes a cloud check that pings /healthz with a 3-second timeout and reports latency. Set ASHLR_API_URL_DISABLE=1 to suppress it in offline environments.

---

Status-line

The status bar shows live session savings with a 7-day Braille sparkline:

┌─────────────────────────────────────────────┐
│  ashlr  −0 tok  $0.00  ▁▁▁▁▁▁▁  idle       │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│  ashlr  −12,480 tok  $0.04  ▁▂▃▄▅▆█  ██    │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│  ashlr  −48,200 tok  $0.14  ▁▃▅▆██  ▓▓▓ !! │
└─────────────────────────────────────────────┘

!! appears when context pressure is high. Install:

bun run ~/.claude/plugins/cache/ashlr-marketplace/ashlr/<version>/scripts/install-status-line.ts

---

Install

Prerequisites: Claude Code. bun ≥ 1.3 is auto-installed on first MCP server spawn — opt out with ASHLR_NO_AUTO_INSTALL=1. No account, no API key.

# One-liner
curl -fsSL plugin.ashlr.ai/install.sh | bash

Then inside Claude Code:

/plugin marketplace add ashlrai/ashlr-plugin
/plugin install ashlr@ashlr-marketplace
/reload-plugins

Verify with /ashlr-status. If /reload-plugins is unavailable or /ashlr-status does not see the plugin, fully quit and restart Claude Code.

Manual install:

git clone https://github.com/ashlrai/ashlr-plugin \
  ~/.claude/plugins/cache/ashlr-marketplace/ashlr
cd ~/.claude/plugins/cache/ashlr-marketplace/ashlr && bun install
# Then inside Claude Code:
# /plugin marketplace add ashlrai/ashlr-plugin
# /plugin install ashlr@ashlr-marketplace
# /reload-plugins

---

Commands

Command	Description
/ashlr-help	List every ashlr slash command grouped by purpose (Onboarding / Token meter / Genome / Upgrade / Diagnostics)
/ashlr-allow	Auto-approve every ashlr MCP tool — covers canonical mcp__plugin_ashlr_ashlr__ashlr__* names, run once after install
/ashlr-status	Plugin health + MCP server reachability + genome detection
/ashlr-savings	Live dashboard: session + lifetime + per-tool + 7-day sparkline
/ashlr-doctor	11-check diagnostic — deps, MCP reachability, hooks, settings
/ashlr-tour	60-second guided walkthrough on your current project
/ashlr-benchmark	Token-savings benchmark against your current project
/ashlr-genome-init	Initialize .ashlrcode/genome/ for the −84% grep path
/ashlr-ollama-setup	Diagnose Ollama for --summarize; pull recommended 3B model
/ashlr-settings	View or change plugin toggles
/ashlr-update	git pull + bun install + report what changed

---

Free vs Pro

The free tier is the product — 40 MCP tools, 31 slash commands, the full genome scribe loop, and every benchmark included. No account required.

Pro ($12/mo, 7-day trial) adds cloud infrastructure for developers who need it: cross-machine stats sync, hosted embedding retrieval, cloud LLM summarizer (no local Ollama required), and a live auto-updating savings badge. Team ($24/user/mo, min 3) adds shared encrypted team genome, org savings dashboard, policy packs, and SSO.

Run /ashlr-upgrade to upgrade, or see docs/pricing.md for the full comparison.

---

Architecture

See docs/architecture.md for how the tools, hooks, and genome scribe loop fit together.

Changelog

See CHANGELOG.md for version history.

License

MIT — LICENSE.