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.

>

> ```bash

> 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/.json`. Toggle with `/ashlr- 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):

Shell, data, and web tools:

Codebase navigation:

Genome + GitHub:

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:

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//scripts/install-status-line.ts

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

Commands

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.

License

MIT — LICENSE.