ashlr-plugin

Same agent. Fewer tokens.

Fewer tokens per tool call in Codex and Claude Code: reads about −75%, greps about −27% on vercel/ai, pandas and tokio (per-call benchmark, not end to end). TS −60% · Python −63% · Rust −55% — 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

The npm package exposes ashlr-plugin for CLI workflows and ashlr-mcp for MCP hosts. It requires Bun. From v1.36.4, use ashlr-plugin stats, ashlr-plugin tools, and other Plugin commands in place of the former ashlr alias; ashlr remains available to Ashlr Hub. MCP server registration names and tool names are unchanged.

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

Open-source and honestly benchmarked. The per-call figures are 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)

• Tools act on your project — MCP tools resolve relative paths and default folders against the folder the host launched them in, not the plugin's install folder. Phantom fleet worktrees are no longer refused.
• Faster hooks — each SessionStart and PostToolUse event starts one node launcher instead of one per hook (CPU per native Edit 712 → 319 ms in a Linux container), and SessionStart exits in about 0.6 s instead of 2.1 s.
• Claude Code hooks detected correctly — hooks under Claude Code no longer run in Codex nudge mode.
• Works without Bun on PATH — the npm bins start under node and find or explain Bun instead of failing with env: 'bun'.
• Readable grep fallback — ashlr__grep without a genome returns plain path:line:text matches, says when ripgrep stopped early, and is benchmarked against plain rg -n (about −27% per call).
• Shorter edit replies — exact, unique ashlr__edit matches return the header only.
• New host ids — ASHLR_MCP_HOST=gemini-cli and cursor.

See the CHANGELOG for the full list.

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. For a fast Codex setup, see the Codex quickstart.

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.

# 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   ▁▂▃▃▅▆█

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.

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.

The Claude Code status bar shows session savings, a 7-day sparkline, and optional context pressure. The examples below are representative; counters and optional badges depend on your session and settings.

┌─────────────────────────────────────────────┐
│  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

The optional statusLine settings live under the ashlr key in ~/.claude/settings.json. Omitted booleans use the defaults shown here.

For example, to hide tips and lifetime totals while keeping session savings:

{
  "ashlr": {
    "statusLineTips": false,
    "statusLineLifetime": false
  }
}

The status line is Claude Code-specific. Codex users can inspect savings with ashlr-plugin stats --json or the ashlr__savings MCP tool.

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

The plugin's own provider calls (the summarizer and token-count calls to Anthropic, the genome reachability probes for Anthropic and OpenAI, and the Ollama checks in /ashlr-ollama-setup and genome-init) read the usual environment variables and keep their old defaults when none is set:

Trailing slashes are trimmed. Pointing these at a gateway such as a LiteLLM proxy or a Phantom proxy is therefore possible, because the plugin just sends its requests to whatever URL you set. Only the URL handling is covered by tests here; the plugin has not been tested against any specific gateway, and what a gateway does with your keys and requests is documented by that gateway. Not covered: the Ollama probe in the session greeting and the optional ASHLR_EMBED_URL embedding endpoint, which keep their own settings.

/ashlr-doctor also lists whether the optional Phantom CLI is installed and which version. It runs only phantom --version and never reads or reveals secret values. To run tools with Phantom placeholder keys and base URLs, start them with phantom exec -- <cmd>.

Running the doctor and benchmark scripts under Phantom is supported only through phantom exec, for example phantom exec -- bun run scripts/doctor.ts or phantom exec -- bun run scripts/run-benchmark.ts --validate-tokenizer. Inside such a session the doctor's phantom exec line reports the proxy port, which provider keys hold phm_ placeholders and which base URLs point at the local proxy (with the session token redacted). It warns when a key is a phm_ placeholder outside a session, when a placeholder's base URL does not point at the proxy, or when a key is a phm: reference. The plugin never resolves phm: references, never runs phantom reveal and never prints key values; run-benchmark --validate-tokenizer skips the API sample when the key would not work from that process. Detection uses variable names, the phm prefixes and the base URL host and port only; it has not been tested against a live Phantom session here.

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.

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

See CHANGELOG.md for version history.

The Ashlr plugin is one of the open-source tools from Ashlr, a forward-deployed engineering company. Its siblings: Lexicon, Locus, Phantom Secrets, Ashlr Stack, Ashlr Markdown.

Issues and PRs are welcome. Look for good first issue to get started, and read CONTRIBUTING.md. Report security problems privately per SECURITY.md.

MIT — LICENSE.