ashlr-plugin

★ 2

from ashlrai

Open-source Claude Code plugin replacing Read/Grep/Edit/Bash with token-efficient versions. Independently benchmarked at 57% token reduction on real codebases. 40 MCP tools.

🔥🔥🔥🔥✓ VerifiedPaid serviceNeeds API keys

#automation #database #git #memory

ashlr-plugin

Cut Codex and Claude Code token usage by −57% on real codebases. TS −62% · Python −65% · Rust −44% — measured on vercel/ai, pandas, and tokio. 95% CI reported by the benchmark runner. Reproduce with bun run scripts/run-benchmark.ts --compare. (full methodology)

40 MCP tools that replace high-volume Read / Grep / Edit / Bash workflows with versions that return less without losing what matters. Claude Code gets automatic PreToolUse redirects (ASHLR_HOOK_MODE=redirect); Codex gets first-class plugin packaging, MCP, skills, and nudge-first hooks.

Requires Bun ≥ 1.3 — interactive installers can offer to install Bun; piped/non-interactive installs skip that prompt and rely on MCP bootstrap if Bun is missing. Verify with bun --version first.
curl -fsSL https://bun.sh/install | bash

# macOS / Linux
curl -fsSL https://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 · Docs: plugin.ashlr.ai/docs · Core library: @ashlr/core-efficiency · License: MIT

Open-source and honestly benchmarked. The −57% headline is reproducible on your own code with bun run scripts/run-benchmark.ts --compare (methodology). Every ashlr savings figure includes a 95% CI. Telemetry is off by default. Compare against closed, self-benchmarked alternatives with /ashlr-benchmark --compare.

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

What's new in v1.36

Codex-native plugin packaging — .codex-plugin/plugin.json, .mcp.json, Codex workflow skills, Codex explorer/worker agent guidance, and portable Codex hooks ship in the same package as the Claude Code plugin.
Reliable Codex MCP launch — ashlr-mcp starts the router directly with ASHLR_MCP_HOST=codex-cli, workspace-aware cwd behavior, and ASHLR_ALLOW_PROJECT_PATHS support for non-plugin launch directories.
Codex nudge-first hooks — Codex hooks now inject compact-tool guidance for Bash, apply_patch, Read/Grep/Glob, Edit/MultiEdit, Write, and high-value Ashlr MCP calls without forcing redirects by default.
Host-neutral CLI workflows — ashlr codex-doctor, ashlr codex-install --dry-run, ashlr codex-start, ashlr codex-resume, ashlr codex-end, and ashlr genome-refresh give Codex users the same operational surface without writing Claude config.
Four discipline skills — /ashlr-search, /ashlr-lean-tools, /ashlr-genome-author, /ashlr-cost-refactor. Each enforces a specific anti-waste pattern; each persists in ~/.ashlr/<name>.json. Toggle with /ashlr-<name> on/off.
/ashlr-efficient — output structure reshaper. Enforces answer-first (inverted pyramid), inline code for all identifiers, tables for 3+ item comparisons, and no transitional filler. Works standalone or alongside /ashlr-brief.
Two lifecycle hooks — SubagentStop rolls up subagent savings to the session log and fires background genome consolidation; Stop finalises session stats with an idempotency guard. (Re-orientation after context compaction is handled by the SessionStart compact hook, the only event that can inject context.)
API-measured savings mode — when ANTHROPIC_API_KEY is set, token counts upgrade from (est.) to (API-measured) once ≥10 calls have been verified via the Anthropic API. Fire-and-forget; SHA-256 cached; never blocks a tool call.
Benchmark transparency — scripts/run-benchmark.ts now reports a 95% bootstrap confidence interval alongside the headline. New flags: --compare (A/B table), --validate-tokenizer (API spot-check of the chars/4 heuristic). See benchmark methodology.

v1.33 highlights

First-call savings projection — see your annual savings extrapolated on your very first ashlr call.
Multi-host MCP — works in Codex, Claude Code, Cline, Claude Desktop, Cursor, Goose, and generic MCP hosts (ASHLR_MCP_HOST env var).
/ashlr-orchestrate-status — inspect past orchestration runs with per-node timings + tokens.
Orchestration retry + handoff budget — per-node retry-with-backoff; HANDOFF_PAYLOAD capped at 8KB.
Orchestration central quota accounting — orchestration_usage table for Team-tier soft-throttle.
Bun ≥ 1.3 prereq surfaced + wizard restart enforcement — closes 2 fatal first-touch cliffs.
Orchestrator overhead bench — measured ~5-30ms/node, 2.8× parallel speedup vs sequential.
Pre-existing tsc errors fixed + permanent dashboard date-drift fix via clock injection.

What's new in v1.33 (archived)

v1.32 highlights

/ashlr-orchestrate — multi-agent task graphs with parallel execution, dry-run renderer, and tier-gated subprocess wiring.
/ashlr-orchestrate-status — inspect past orchestration runs with per-node telemetry and 2.8× measured parallel speedup.
Live genome — PR-aware + commit-aware sections via git post-commit hook and GitHub webhook delta sync.
AI-Native discoveries — LLM synthesizes discovery sections from your commit history automatically.
Predictive prefetch (Pro/Team) — background warm-cache on every ashlr__read cuts repeat-hit latency.
PR + issue retrieval — ashlr__grep --include-prs --include-issues --since-days pulls live GitHub context.
Freshness badges in genome retrieval surface staleness so you trust the answer.
Cross-language bench: TS −61.3% · Python −63.1% · Rust −46.8% (cross-language headline -57.1% holds).
Founder WAD-D dashboard at /admin/wad-d — daily-active records + segment breakdown + discovery propagation.

Multi-host MCP

Works with Codex, Claude Code (default), Cline, Claude Desktop, Cursor, Goose, and generic MCP hosts. The 40 MCP tools, stats accounting, and genome retrieval are host-agnostic; savings and accounting apply when the host calls Ashlr MCP tools. Codex support is packaged through .codex-plugin/plugin.json, .mcp.json, Codex skills, and hooks/codex-hooks.json in nudge mode. Claude-only extras remain explicitly labeled: auto redirects, status line, slash commands, and OAuth bootstrap. See plugin.ashlr.ai/docs or docs/multi-host-mcp.md for setup snippets.

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 https://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.36.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 https://api.ashlr.ai/llm/summarize` — cloud inference via xAI Grok 4.3. Falls back to local summarization or snipCompact when unavailable.
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 plugin.ashlr.ai/docs for the full privacy contract (internal: docs/telemetry.md).

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

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, 34 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 plugin.ashlr.ai/docs/pro/pricing for the full comparison.

Architecture

See plugin.ashlr.ai/docs/contributing/architecture for how the tools, hooks, and genome scribe loop fit together. Internal notes: docs/architecture.md.

Changelog

See CHANGELOG.md for version history.

Install

Prerequisites: Bun ≥ 1.3 and at least one supported host: Codex CLI, Claude Code, Cursor, Goose, or another MCP-capable client. Interactive installers can offer to install Bun; piped/non-interactive installs skip that prompt and rely on MCP bootstrap if Bun is missing. Verify with bun --version first, or install: curl -fsSL https://bun.sh/install | bash. No account, no API key.

# Claude Code one-liner
curl -fsSL https://plugin.ashlr.ai/install.sh | bash

For Codex:

git clone https://github.com/ashlrai/ashlr-plugin
cd ashlr-plugin && bun install
codex plugin marketplace add ashlrai/ashlr-plugin
codex plugin add ashlr@ashlr-marketplace
bun run scripts/cli.ts codex-doctor --json

For 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