# ashlr-plugin

> Install with npm, call the CLI with --json, and register the ashlr-mcp server.

## Start here

- [Capabilities and install](https://plugin.ashlr.ai/docs/capabilities): Supported hosts, requirements, tools, installation, and verification.
- [Full documentation](https://plugin.ashlr.ai/llms-full.txt): README and complete documentation source.

## Product and policies

- [Home](https://plugin.ashlr.ai/): Product overview
- [Benchmarks](https://plugin.ashlr.ai/benchmarks): Reproducible per-call token savings
- [Compare](https://plugin.ashlr.ai/compare): Feature comparisons with other coding tools
- [Pricing](https://plugin.ashlr.ai/pricing): Free plugin and optional paid services
- [Roadmap](https://plugin.ashlr.ai/roadmap): Shipped milestones and planned work
- [Community](https://plugin.ashlr.ai/community): Aggregate usage and savings
- [FAQ](https://plugin.ashlr.ai/faq): Plain answers for agents and humans
- [Blog](https://plugin.ashlr.ai/blog): Engineering and release posts
- [Privacy](https://plugin.ashlr.ai/privacy): Data collection, retention, and rights
- [Terms](https://plugin.ashlr.ai/terms): Terms of service
- [DPA](https://plugin.ashlr.ai/dpa): Data Processing Addendum
- [Why I built a token-efficiency layer for Codex and Claude Code](https://plugin.ashlr.ai/blog/2026-04-18-introducing-ashlr): Token counts are a real operating cost. ashlr is the open-source plugin that fixes the read-everything problem in Codex and Claude Code : cutting mean token usage by 57% across TypeScript, Python, and Rust reference repos.
- [Fixing the session counter: when CLAUDE_SESSION_ID disappears at the process boundary](https://plugin.ashlr.ai/blog/2026-04-18-fixing-the-session-counter): Users were seeing 'session +0' even as lifetime savings climbed. The root cause: CLAUDE_SESSION_ID is not forwarded to MCP server subprocesses. Here's how we diagnosed it and what candidateSessionIds() does to fix it.
- [Client-side encryption for team genomes: threat model, key management, and the AES-256-GCM implementation](https://plugin.ashlr.ai/blog/2026-04-18-encryption-for-team-genomes): v1.8.0 shipped client-side AES-256-GCM encryption for shared team genomes. This post walks through the threat model, how keys are managed, and how encryption pairs with the vclock-based sync layer.

## README and documentation

- [README](https://github.com/ashlrai/ashlr-plugin/blob/main/README.md): ashlr-plugin; Install; MCP server; How it works; Tool calls; Features; FAQ; Does an agent need an account?; Where do file contents go?; What does a savings number mean?; Which hosts get slash commands?; What is Pro?; Star; Releasing; Automatic releases; Release notes; Status-line; Provider base URLs; Plugs into Phantom Secrets; Commands; Free vs Pro; Architecture; Changelog; Part of the Ashlr ecosystem; Contributing; License
- [ashlr docs](https://plugin.ashlr.ai/docs): Install; Documentation map; Start here; MCP tools (54); Commands + Skills; Concepts; Pro / Team; Contributing
- [Capabilities and install](https://plugin.ashlr.ai/docs/capabilities): Capabilities; Install; Verify your installation; Agent entry points
- [Concepts](https://plugin.ashlr.ai/docs/concepts): Pages in this section; Where these connect
- [Animation](https://plugin.ashlr.ai/docs/concepts/animation): Gradient sweep; Heartbeat; Activity pulse; Landing page animations
- [Confidence badges](https://plugin.ashlr.ai/docs/concepts/confidence-badges): Tier definitions; Tier math; Fallback semantics; What the badge means for your workflow; Status line
- [Environment variables reference](https://plugin.ashlr.ai/docs/concepts/env-vars): Core behavior; Storage paths; Session accounting; Summarization and LLM; Genome; Pro / Cloud; Telemetry; UI / status line; Access control; Experimental; No-install; Related
- [Genome](https://plugin.ashlr.ai/docs/concepts/genome): What is in the genome; The propose/consolidate loop; Scribe loop settings; Team sharing; Genome vs ripgrep; Related
- [Automatic hooks](https://plugin.ashlr.ai/docs/concepts/hooks): SubagentStop : savings rollup after a Task finishes; Stop : session finalization; Session log location; All hooks are fire-and-forget safe
- [How session savings are counted](https://plugin.ashlr.ai/docs/concepts/savings-math): The 2 KB compression threshold; Bash invocations and hook modes; ashlr__edit accounting is conservative; Sub-agent invocations are credited to the agent, not you; Genome dependence for ashlr__grep; Session-length effect; Where to verify the actual numbers; API-measured vs estimated savings; Related
- [snipCompact : head + tail trimming](https://plugin.ashlr.ai/docs/concepts/snipcompact): The algorithm; Why head + tail; The 2 KB threshold; LLM summarization (≥ 16 KB); Savings data; Related
- [Stats schema](https://plugin.ashlr.ai/docs/concepts/stats-schema): Top-level shape; LifetimeBucket; SessionBucket; CalibrationState; Migration from v1; Session log
- [Status line](https://plugin.ashlr.ai/docs/concepts/status-line): Installation and troubleshooting
- [Contributing](https://plugin.ashlr.ai/docs/contributing): Pages in this section; Quickstart; What we're looking for; What gets rejected
- [Architecture](https://plugin.ashlr.ai/docs/contributing/architecture): Two value propositions; MCP server map; Key shared modules; Adding a new MCP tool; See also
- [Releases](https://plugin.ashlr.ai/docs/contributing/releases): Version scheme; Release checklist; Publishing manually; Changelog format; Deprecation policy
- [Testing](https://plugin.ashlr.ai/docs/contributing/testing): Test runner; Run all tests; Run a specific test file; Run tests matching a pattern; Test organization; Writing a new test; CI; Type checking
- [What is ashlr?](https://plugin.ashlr.ai/docs/getting-started): How an agent uses it; What the tools change; Install; What's included
- [Install](https://plugin.ashlr.ai/docs/getting-started/install): npm CLI and MCP entrypoints; Claude Code; Codex; Cursor; Goose; Requirements
- [Permissions](https://plugin.ashlr.ai/docs/getting-started/permissions): What it does; Entries added; Scope; Dry run; Undo; Reload required
- [Quickstart](https://plugin.ashlr.ai/docs/getting-started/quickstart): Step 1 - run a host check; Step 2 - call ashlr__read directly; Step 3 - check the ledger; Step 4 - approve all tools in Claude Code; Next steps
- [Pro tier](https://plugin.ashlr.ai/docs/pro): Pages in this section; What "hosted" gets you; Privacy commitments
- [Pro backend](https://plugin.ashlr.ai/docs/pro/backend): Components; Stats sync; Cloud LLM summarizer; Genome sync (Team); Auto-updating badge; Security; Self-hosting; Related
- [Cloud genome](https://plugin.ashlr.ai/docs/pro/cloud-genome): What the cloud genome is; How sync works; End-to-end encryption; Setup; Pro (personal, cross-machine); Team (shared genome); Privacy; Related
- [Hosted summarization](https://plugin.ashlr.ai/docs/pro/hosted-summarization): What it does; When it fires; Privacy; Setup; Confidence badges; Local fallback (free tier / offline); Related
- [Pricing](https://plugin.ashlr.ai/docs/pro/pricing): Plans; Free tier is complete; Related
- [Pro setup](https://plugin.ashlr.ai/docs/pro/setup): Get a token; Configure the token; Verify; What you get; Team tokens; Related
- [Latest release](https://plugin.ashlr.ai/docs/release): Released 1.38.4 (2026-11-06); Fixed
- [Commands and workflow skills](https://plugin.ashlr.ai/docs/skills): Slash commands; /ashlr-allow; /ashlr-benchmark; /ashlr-brief; /ashlr-budget; /ashlr-compact; /ashlr-dashboard; /ashlr-doctor; /ashlr-eco-mode; /ashlr-fleet; /ashlr-genome-init; /ashlr-genome-keygen; /ashlr-genome-loop; /ashlr-genome-push; /ashlr-genome-rewrap; /ashlr-genome-team-init; /ashlr-handoff; /ashlr-help; /ashlr-hook-timings; /ashlr-leaderboard; /ashlr-legend; /ashlr-ollama-setup; /ashlr-orchestrate-status; /ashlr-orchestrate; /ashlr-parallelize; /ashlr-report-crash; /ashlr-resume; /ashlr-savings; /ashlr-selftest; /ashlr-settings; /ashlr-spawn; /ashlr-start; /ashlr-status; /ashlr-team-invite; /ashlr-tier; /ashlr-tour; /ashlr-update; /ashlr-upgrade; Workflow skills; ashlr-brief; ashlr-codex-doctor; ashlr-codex-efficient-tools; ashlr-codex-genome-refresh; ashlr-codex-parallel-explore; ashlr-codex-savings; ashlr-cost-refactor; ashlr-efficient; ashlr-genome-author; ashlr-lean-tools; ashlr-search
- [/ashlr-allow](https://plugin.ashlr.ai/docs/skills/allow): When to use; What it does; Output; Undo; Related
- [/ashlr-benchmark](https://plugin.ashlr.ai/docs/skills/benchmark): When to use; What it does; Output; Advanced flags; Confidence intervals; Methodology; Related
- [/ashlr-brief](https://plugin.ashlr.ai/docs/skills/brief): Quick start; Intensity levels; Auto-clarity exceptions; Activation methods; Pro/Team : project-level enforcement; Status line; Real-data evaluation; See also
- [/ashlr-budget](https://plugin.ashlr.ai/docs/skills/budget): Usage; Environment variables; Steps; $X : set USD cap; tokens=N : set token cap; status : print current usage; off : clear the budget cap; Budget guard behavior (implemented in hooks/pretooluse-budget-guard.ts)
- [ashlr-codex-doctor](https://plugin.ashlr.ai/docs/skills/codex-doctor): ashlr-codex-doctor
- [ashlr-codex-efficient-tools](https://plugin.ashlr.ai/docs/skills/codex-efficient-tools): ashlr-codex-efficient-tools
- [ashlr-codex-genome-refresh](https://plugin.ashlr.ai/docs/skills/codex-genome-refresh): ashlr-codex-genome-refresh
- [ashlr-codex-parallel-explore](https://plugin.ashlr.ai/docs/skills/codex-parallel-explore): ashlr-codex-parallel-explore
- [ashlr-codex-savings](https://plugin.ashlr.ai/docs/skills/codex-savings): ashlr-codex-savings
- [/ashlr-compact](https://plugin.ashlr.ai/docs/skills/compact): /ashlr-compact
- [/ashlr-cost-refactor](https://plugin.ashlr.ai/docs/skills/cost-refactor): Quick start; The refactor sequence; Rules; When to enable; Persistence; Related
- [/ashlr-dashboard](https://plugin.ashlr.ai/docs/skills/dashboard): When to use; What it does; Output; Related
- [/ashlr-doctor](https://plugin.ashlr.ai/docs/skills/doctor): When to use; What it does; Output; Related
- [/ashlr-eco-mode](https://plugin.ashlr.ai/docs/skills/eco-mode): Usage; What eco mode does; Environment variable; Steps; on; off; status; No argument
- [/ashlr-efficient](https://plugin.ashlr.ai/docs/skills/efficient): Quick start; Rules; 1. Inverted pyramid : answer first; 2. Inline code for all identifiers and paths; 3. Tables for 3+ item comparisons; 4. No transitional filler; 5. file:line citations instead of quoted blocks; Auto-clarity exceptions; Combined with /ashlr-brief; Persistence; Related
- [/ashlr-fleet](https://plugin.ashlr.ai/docs/skills/fleet): /ashlr-fleet
- [/ashlr-genome-author](https://plugin.ashlr.ai/docs/skills/genome-author): Quick start; What it does; When to propose; When NOT to propose; Summary format; Persistence; Related
- [/ashlr-genome-init](https://plugin.ashlr.ai/docs/skills/genome-init): When to use; What it does; Output; After init; Related
- [/ashlr-genome-keygen](https://plugin.ashlr.ai/docs/skills/genome-keygen): What it does; Why
- [/ashlr-genome-loop](https://plugin.ashlr.ai/docs/skills/genome-loop): When to use; What it does; Output; Commands; Related
- [/ashlr-genome-push](https://plugin.ashlr.ai/docs/skills/genome-push): What it does
- [/ashlr-genome-rewrap](https://plugin.ashlr.ai/docs/skills/genome-rewrap): When to use; What it does; Flags; Exit codes; Related
- [/ashlr-genome-team-init](https://plugin.ashlr.ai/docs/skills/genome-team-init): What it does (fresh init); What it does (--wrap-all); Typical team setup
- [/ashlr-handoff](https://plugin.ashlr.ai/docs/skills/handoff): When to use; What it does; Output (example); Related
- [/ashlr-help](https://plugin.ashlr.ai/docs/skills/help): /ashlr-allow; /ashlr-benchmark; /ashlr-brief; /ashlr-budget; /ashlr-compact; /ashlr-dashboard; /ashlr-doctor; /ashlr-eco-mode; /ashlr-fleet; /ashlr-genome-init; /ashlr-genome-keygen; /ashlr-genome-loop; /ashlr-genome-push; /ashlr-genome-rewrap; /ashlr-genome-team-init; /ashlr-handoff; /ashlr-help; /ashlr-hook-timings; /ashlr-leaderboard; /ashlr-legend; /ashlr-ollama-setup; /ashlr-orchestrate-status; /ashlr-orchestrate; /ashlr-parallelize; /ashlr-report-crash; /ashlr-resume; /ashlr-savings; /ashlr-selftest; /ashlr-settings; /ashlr-spawn; /ashlr-start; /ashlr-status; /ashlr-team-invite; /ashlr-tier; /ashlr-tour; /ashlr-update; /ashlr-upgrade
- [/ashlr-hook-timings](https://plugin.ashlr.ai/docs/skills/hook-timings): /ashlr-hook-timings
- [/ashlr-leaderboard](https://plugin.ashlr.ai/docs/skills/leaderboard): Usage; What gets published when you opt in; How to apply this; Requirements & notes
- [/ashlr-lean-tools](https://plugin.ashlr.ai/docs/skills/lean-tools): Quick start; Rules; When to enable; Persistence; Related
- [/ashlr-legend](https://plugin.ashlr.ai/docs/skills/legend): When to use; What it does; Related
- [/ashlr-ollama-setup](https://plugin.ashlr.ai/docs/skills/ollama-setup): When to use; What it does; Output; Minimum requirements; Related
- [/ashlr-orchestrate](https://plugin.ashlr.ai/docs/skills/orchestrate): Description; Usage examples; Tier gates; Output; Invocation
- [/ashlr-orchestrate-status](https://plugin.ashlr.ai/docs/skills/orchestrate-status): Description; Usage examples; Output; Invocation
- [/ashlr-parallelize](https://plugin.ashlr.ai/docs/skills/parallelize): Usage; Examples; Steps; Illustrative output
- [/ashlr-report-crash](https://plugin.ashlr.ai/docs/skills/report-crash): /ashlr-report-crash
- [/ashlr-resume](https://plugin.ashlr.ai/docs/skills/resume): Usage; What it shows; Behavior; Limitations; Implementation
- [/ashlr-savings](https://plugin.ashlr.ai/docs/skills/savings): When to use; What it does; Output; Savings methodology; "Why are my savings lower than the headline?"; Related
- [/ashlr-search](https://plugin.ashlr.ai/docs/skills/search): Quick start; What it does; When to enable; Persistence; Related
- [/ashlr-selftest](https://plugin.ashlr.ai/docs/skills/selftest): /ashlr-selftest
- [/ashlr-settings](https://plugin.ashlr.ai/docs/skills/settings): When to use; What it does; Output (view); Changing a setting; Related settings; Related
- [/ashlr-spawn](https://plugin.ashlr.ai/docs/skills/spawn): Patterns available; Argument convention; Steps
- [/ashlr-start](https://plugin.ashlr.ai/docs/skills/start): --reset flag; Normal wizard flow; Rules
- [/ashlr-status](https://plugin.ashlr.ai/docs/skills/status): When to use; What it does; Output; Related
- [/ashlr-team-invite](https://plugin.ashlr.ai/docs/skills/team-invite): /ashlr-team-invite
- [/ashlr-tier](https://plugin.ashlr.ai/docs/skills/tier): Usage; How it works; Examples; Steps
- [/ashlr-tour](https://plugin.ashlr.ai/docs/skills/tour): When to use; What it does; Output style; Related
- [/ashlr-update](https://plugin.ashlr.ai/docs/skills/update): When to use; What it does; Output; Related
- [/ashlr-upgrade](https://plugin.ashlr.ai/docs/skills/upgrade): Invocation; Flags; Handling ASHLR_PROMPT: ... markers; Error handling; Rules
- [MCP tools](https://plugin.ashlr.ai/docs/tools): ashlr__glob; ashlr__tree; ashlr__ls; ashlr__diff; ashlr__webfetch; ashlr__read; ashlr__flush; ashlr__edit_structural; ashlr__rename_file; ashlr__search_replace_regex; ashlr__websearch; ashlr__task_list; ashlr__task_get; ashlr__notebook_edit; ashlr__pipe; ashlr__fleet_state; ashlr__fleet_events; ashlr__fleet_intent; ashlr__fleet_session; ashlr__fleet_act; ashlr__fleet_snapshot; ashlr__fleet_direction; ashlr__fleet_lanes; ashlr__fleet_proposals; ashlr__fleet_propose; ashlr__fleet_browser; ashlr__fleet_resources; ashlr__grep; ashlr__edit; ashlr__write; ashlr__http; ashlr__logs; ashlr__sql; ashlr__diff_semantic; ashlr__pr; ashlr__issue; ashlr__pr_comment; ashlr__pr_approve; ashlr__issue_create; ashlr__issue_close; ashlr__genome_propose; ashlr__genome_consolidate; ashlr__genome_status; ashlr__fleet_ghosts; ashlr__fleet_dirty_triage; ashlr__multi_edit; ashlr__orient; ashlr__bash; ashlr__bash_start; ashlr__bash_tail; ashlr__bash_stop; ashlr__bash_list; ashlr__test; ashlr__savings; ashlr__ask
- [ashlr__ask](https://plugin.ashlr.ai/docs/tools/ask): Input schema; Routing table; Output format; Example; Related tools
- [ashlr__bash](https://plugin.ashlr.ai/docs/tools/bash): Tools exposed; Input schema : ashlr__bash; Output format; Example; Related tools
- [ashlr__bash_list](https://plugin.ashlr.ai/docs/tools/bash-list): Tool names
- [ashlr__bash_start](https://plugin.ashlr.ai/docs/tools/bash-start): Tool names
- [ashlr__bash_stop](https://plugin.ashlr.ai/docs/tools/bash-stop): Tool names
- [ashlr__bash_tail](https://plugin.ashlr.ai/docs/tools/bash-tail): Tool names
- [Capabilities matrix](https://plugin.ashlr.ai/docs/tools/capabilities): Capabilities matrix
- [ashlr__diff](https://plugin.ashlr.ai/docs/tools/diff): Input schema; Output format; Example; Savings baseline; Related tools
- [ashlr__diff_semantic](https://plugin.ashlr.ai/docs/tools/diff-semantic): Semantic analysis passes; Input schema; Output format; When to use vs ashlr__diff; Related tools
- [ashlr__edit](https://plugin.ashlr.ai/docs/tools/edit): Input schema; Output format; Example; Savings baseline; Strict mode; Related tools
- [ashlr__edit_structural](https://plugin.ashlr.ai/docs/tools/edit-structural): Use cases; Parameters; Supported languages; Example; Related
- [ashlr__flush](https://plugin.ashlr.ai/docs/tools/flush): Parameters; Returns; Typical savings; Related
- [ashlr__genome (tools)](https://plugin.ashlr.ai/docs/tools/genome): Tools; ashlr__genome_propose; ashlr__genome_consolidate; ashlr__genome_status; Output format (status); See also
- [ashlr__genome_consolidate](https://plugin.ashlr.ai/docs/tools/genome-consolidate): Tool names
- [ashlr__genome_propose](https://plugin.ashlr.ai/docs/tools/genome-propose): Tool names
- [ashlr__genome_status](https://plugin.ashlr.ai/docs/tools/genome-status): Tool names
- [ashlr__pr + ashlr__issue](https://plugin.ashlr.ai/docs/tools/github): ashlr__pr; Input schema; Output format; ashlr__issue; Input schema; Output format; Requirement; Related tools
- [ashlr__glob](https://plugin.ashlr.ai/docs/tools/glob): Input schema; Output format; Example; Related tools
- [ashlr__grep](https://plugin.ashlr.ai/docs/tools/grep): Input schema; Example; Related tools
- [ashlr__http](https://plugin.ashlr.ai/docs/tools/http): Input schema; Output format; Private host protection; Example; Related tools
- [ashlr__issue](https://plugin.ashlr.ai/docs/tools/issue): Tool names
- [ashlr__issue_close](https://plugin.ashlr.ai/docs/tools/issue-close): Parameters; Notes; Related
- [ashlr__issue_create](https://plugin.ashlr.ai/docs/tools/issue-create): Parameters; Notes; Related
- [ashlr__logs](https://plugin.ashlr.ai/docs/tools/logs): Severity detection; Input schema; Output format; Example; Savings baseline; Related tools
- [ashlr__ls](https://plugin.ashlr.ai/docs/tools/ls): Parameters; When to use vs ashlr__tree; Related
- [ashlr__multi_edit](https://plugin.ashlr.ai/docs/tools/multi-edit): Input schema; Edit object; Output format; Example; Savings baseline; Related tools
- [ashlr__notebook_edit](https://plugin.ashlr.ai/docs/tools/notebook-edit): Parameters; Notes; Typical savings; Related
- [ashlr__orient](https://plugin.ashlr.ai/docs/tools/orient): Input schema; Output format; Savings baseline; When to use; Related tools
- [ashlr__pipe EXPERIMENTAL](https://plugin.ashlr.ai/docs/tools/pipe): Why it exists; Enable; Usage; Parameters; Available functions inside expr; Deny-list; Token accounting; Example : filter TODO output for auth; Limitations; Related
- [ashlr__pr](https://plugin.ashlr.ai/docs/tools/pr): Tool names
- [ashlr__pr_approve](https://plugin.ashlr.ai/docs/tools/pr-approve): Parameters; Notes; Related
- [ashlr__pr_comment](https://plugin.ashlr.ai/docs/tools/pr-comment): Parameters; Notes; Related
- [ashlr__read](https://plugin.ashlr.ai/docs/tools/read): Input schema; Example; Related tools
- [ashlr__rename_file](https://plugin.ashlr.ai/docs/tools/rename-file): Parameters; Notes; When to use ashlr__edit_structural instead; Related
- [ashlr__savings](https://plugin.ashlr.ai/docs/tools/savings): Tool names
- [ashlr__search_replace_regex](https://plugin.ashlr.ai/docs/tools/search-replace-regex): Parameters; Example; Returns; When to use ashlr__edit_structural instead; Typical savings; Related
- [ashlr__sql](https://plugin.ashlr.ai/docs/tools/sql): Input schema; Output format; Driver detection; Example; Unsupported; Related tools
- [ashlr__task_get](https://plugin.ashlr.ai/docs/tools/task-get): Parameters; Returns; Typical savings; Related
- [ashlr__task_list](https://plugin.ashlr.ai/docs/tools/task-list): Parameters; Returns; Typical savings; Related
- [ashlr__test](https://plugin.ashlr.ai/docs/tools/test): Parameters; Supported runners; Typical output; Typical savings; Related
- [ashlr__tree](https://plugin.ashlr.ai/docs/tools/tree): Input schema; Output format; Example; Savings baseline; Related tools
- [ashlr__webfetch](https://plugin.ashlr.ai/docs/tools/webfetch): Input schema; Output format; Difference from ashlr__http; Example; Related tools
- [ashlr__websearch](https://plugin.ashlr.ai/docs/tools/websearch): Parameters; When to use vs ashlr__webfetch; Typical savings; Related
- [ashlr__write](https://plugin.ashlr.ai/docs/tools/write): Parameters; When to use; Token note; Related


## Current release: v1.38.4

Latest release: v1.38.4 (2026-11-06).
Source candidate carrying the unpublished repairs documented in 1.38.3. The immutable 1.38.3 candidate failed one always-on tool-description contract before publication; its tag, failed producer and artifacts are not reused. This candidate requires its own exact-tag full cross-platform qualification.

### Fixed

- The fleet-intent always-on description fits the retained 200-character catalog limit while naming every action's required fields, the slot range, caller-attributed requested_by, reason and the refusal to execute or accept extra paths/fields. The schema, handler, audited journal and authority checks are unchanged.
- Includes the restored fleet UI cursor/delta/full-history/alias behavior, portable manifest and file-handle custody repairs, and the explicitly documented Windows CI lifecycle budget calibration from the unpublished 1.38.3 source tranche.

## Install

### npm CLI and MCP entrypoints

```sh
npm install -g ashlr-plugin
```

### Claude Code

```sh
curl -fsSL https://plugin.ashlr.ai/install.sh | bash
/plugin marketplace add ashlrai/ashlr-plugin
/plugin install ashlr@ashlr-marketplace
/reload-plugins
```

### Codex

```sh
codex plugin marketplace add ashlrai/ashlr-plugin
codex plugin add ashlr@ashlr-marketplace
ashlr-plugin codex-doctor --json
```

### Cursor

```sh
npm install -g ashlr-plugin
ashlr-plugin tools --json
mkdir -p .cursor
cat > .cursor/mcp.json <<'EOF'
{
  "mcpServers": {
    "ashlr": {
      "command": "ashlr-mcp",
      "args": [],
      "env": {
        "ASHLR_MCP_HOST": "cursor"
      }
    }
  }
}
EOF
```

### Goose

```sh
npm install -g ashlr-plugin
ashlr-plugin tools --json
cat > ashlr-goose.yaml <<'EOF'
version: "1.0"
title: ashlr token-efficiency suite
description: Registers the ashlr MCP router as one Goose extension.
extensions:
  - name: ashlr
    type: stdio
    cmd: ashlr-mcp
    args: []
    env:
      ASHLR_MCP_HOST: generic
EOF
goose run --recipe ashlr-goose.yaml
```

## MCP tools (54 enabled by default)

- `ashlr__glob`: Match file globs instead of native Glob. Honors .gitignore in git repos; groups large result sets by directory with counts and sample paths.
- `ashlr__tree`: View project structure in one call with directory sizes, file counts and optional LOC. Honors .gitignore in git repos; skips common build and dependency directories otherwise.
- `ashlr__ls`: Gitignore-aware directory listing. Compact columnar output with elision past maxEntries (default 80). Set bypassSummary:true to see all entries.
- `ashlr__diff`: Review adaptive git diffs instead of Bash git diff. Accepts refs, staged, unstaged or working; compresses large patches. Use ashlr__diff_semantic for refactors and renames.
- `ashlr__webfetch`: Fetch article text instead of WebFetch. Strips HTML navigation/scripts, elides JSON arrays and caps plain text; default cap 100 KB.
- `ashlr__read`: Read files instead of native Read with compact head/tail or AST summaries. Pass bypassSummary:true to skip LLM summarization; snipCompact truncation still applies.
- `ashlr__flush`: Flush all queued ashlr__edit writes to disk immediately and return a summary of what was committed. Use when you need to read a file you just edited, or at the end of a multi-edit sequence.
- `ashlr__edit_structural`: Rename symbols or extract functions in TS/JS using ASTs instead of native Edit; avoids strings/comments. Supports cross-file rename and dryRun. Use ashlr__edit for literal edits.
- `ashlr__rename_file`: Move a source file and update resolved project imports, including extension elision and directory indexes. Supports dryRun; refuses existing destinations and paths outside cwd.
- `ashlr__search_replace_regex`: Apply bulk regex substitutions instead of native Edit; supports captures, flags and dryRun. Returns match counts. Use ashlr__edit for literals or ashlr__edit_structural for symbol renames.
- `ashlr__websearch`: Search the web instead of WebSearch with domain deduplication and compact snippets. query is required; maxResults defaults to 5, summarize to true.
- `ashlr__task_list`: List tasks instead of TaskList with compact id, status, subject and age columns. Filter by status or owner; limit defaults to 30.
- `ashlr__task_get`: Fetch a task by taskId instead of TaskGet. Returns status, subject and a compact description with head/tail truncation above 2 KB.
- `ashlr__notebook_edit`: Edit one Jupyter notebook cell instead of NotebookEdit. Returns the edited cell and neighbors, eliding unrelated cells. Accepts notebookPath, cellIndex, newSource and optional cellType.
- `ashlr__pipe` [requires ASHLR_PIPE_ENABLE=1]: [EXPERIMENTAL] Executes model-authored JS code server-side ; off by default, enable with ASHLR_PIPE_ENABLE=1. Call ctx.{grep,read,ls,glob} with the wrapped ashlr__ tool args; only the return value enters context. Typical 80–95% token savings vs individual calls. ctx.bash requires the additional ASHLR_PIPE_ALLOW_BASH=1 flag. Example: `return await ctx.grep({pattern:'TODO',cwd:'my project'});` returns the grep tool's text output as a string, which may include status messages.
- `ashlr__fleet_state`: Read fleet targets, holds, last 20 jobs and leader event; ~/.ashlr-runs fallback splits queue/run/ jobs into live, ghost and held (phdrip markers). Read-only; reports unavailable sources; no secrets.
- `ashlr__fleet_events`: Poll typed dispatch and job events with an opaque per-source cursor. Reads complete lines only; limit up to 200. Reports missing, unsafe or malformed sources without raw contents. Read-only.
- `ashlr__fleet_intent`: Queue audited intents; never execute. pause/resume: lane; kill: job_id; reassign: job_id+lane; set-slot: lane+slots(0–1024). Require reason+requested_by (caller attribution). No other fields/paths.
- `ashlr__fleet_session`: Read fleet job's metadata, metrics, live children (parent_job_id), PR, worktree and last 150 log lines; jobs.jsonl (or runs metrics) and logs/<job_id>.log. Redacted; read-only; job ID, never a path.
- `ashlr__fleet_act`: Request fleet pause/resume, kill, reassign, slots or steer; needs requested_by, reason; dry_run defaults true. Kill adds one request per live child naming parent_request. Audited; never executes.
- `ashlr__fleet_snapshot`: Read fleet lanes, complete job upserts, PR links and latest leader event, with ~/.ashlr-runs fallback. Pass cursor for net changes and removed IDs. Reports source errors. Read-only; no paths.
- `ashlr__fleet_direction`: Read project direction (default VISION.md) or propose changes with author/text. Proposals append only to DIRECTION-PROPOSED.md; never adopt direction or write VISION.md or MASON-INBOX.md.
- `ashlr__fleet_lanes`: Read fleet lane targets, holds, job counts and source errors as JSON using fleet-steer lanes. Read-only; fixed ~/.ashlr/fleet root, no arguments or paths.
- `ashlr__fleet_proposals`: Read the fleet steering proposal journal and skipped-record count as JSON using fleet-steer proposals. Read-only; fixed ~/.ashlr/fleet/steer-proposals.jsonl, no arguments or paths.
- `ashlr__fleet_propose`: Propose fleet reassign or set-slots for controller review, requiring author and reason. Rejects duplicate pending proposals; only appends the steering journal, never applies changes.
- `ashlr__fleet_browser`: Read paged browser frames, latest frame and URL for a validated fleet job ID. Pass cursor for polling; limit defaults to 100, maximum 200. Read-only; accepts a job ID, never a path.
- `ashlr__fleet_resources`: Read fleet resource availability, cap headroom, slot targets, throughput and exhaustion estimates. Refreshes missing or stale (>60s) ledger via ashlr resources --json. No arguments or paths.
- `ashlr__grep`: Search instead of native Grep. Uses genome sections, merged PRs and closed issues when available; otherwise ripgrep with LLM summarization for large results. Returns compact relevant chunks.
- `ashlr__edit`: Replace one literal match instead of native Edit; returns a compact diff. Strict mode requires one match. Use ashlr__multi_edit for multiple files or ashlr__edit_structural for symbol renames.
- `ashlr__write`: Write a file without echoing its contents. Existing files use ashlr__edit for compact full-file replacement; new files return path, byte count and hash.
- `ashlr__http`: HTTP fetch with compressed output. Readable-extracts main content from HTML, pretty-prints + array-elides JSON, bounded byte cap. Refuses non-http/https schemes and private hosts by default.
- `ashlr__logs`: Tail logs with severity and ISO timestamp filters; collapse repeated lines. Supports glob paths, JSON/logfmt levels and Python tracebacks. since skips lines without parseable timestamps.
- `ashlr__sql`: Run SQLite or Postgres queries and return compact text results. Supports SELECT, DDL, DML, EXPLAIN and schema introspection in one call.
- `ashlr__diff_semantic`: Summarize refactors instead of raw git diff with heuristic AST-aware rename, signature and formatting detection. Use instead of ashlr__diff for refactors; falls back to compact diff.
- `ashlr__pr`: Fetch a GitHub PR as a compact review summary: header, reviews, unresolved comments and checks. Read-only; never approves, comments or merges.
- `ashlr__issue`: Fetch a GitHub issue and return a compact header + body + comment list. In 'thread' mode, each comment is rendered with snipCompact on > 500 char bodies. Read-only.
- `ashlr__pr_comment`: Post a comment on a GitHub PR. Pass pr:"current" to target the PR for the checked-out branch. Returns the new comment URL.
- `ashlr__pr_approve`: Approve a GitHub PR with an optional review body. Refuses to approve your own PR. Pass pr:"current" to target the PR for the checked-out branch.
- `ashlr__issue_create`: Create a new GitHub issue with title + body and optional labels/assignees. Returns the new issue number and URL.
- `ashlr__issue_close`: Close a GitHub issue with an optional closing comment and reason (completed|not_planned).
- `ashlr__genome_propose`: Queue an update to a named genome section for the next ashlr__genome_consolidate call. Record decisions, strategies and lessons so they persist across sessions.
- `ashlr__genome_consolidate`: Merge queued genome proposals. Applies sequentially without a model or ASHLR_LLM_URL; with an LLM configured, merges conflicting proposals for the same section.
- `ashlr__genome_status`: Show pending proposals and recent mutations for the current genome. Compact report suitable for inline context.
- `ashlr__fleet_ghosts`: Read ghost slots, stalled jobs and reported versus live counts by lane from ~/.ashlr/fleet/runs. Read-only JSON; unknown liveness and missing sources remain explicit. No arguments or paths.
- `ashlr__fleet_dirty_triage`: Rank DIRTY PRs as recut-worthy, superseded or stale with C1-C6 reasons. repos defaults to current repo; staleDays to 14. Read-only pinned Locus queries; reports partial errors and truncation.
- `ashlr__multi_edit`: Apply edits across files atomically instead of separate Edit calls; rolls back on failure and returns one diff summary. Use ashlr__edit for one file or ashlr__edit_structural for symbol renames.
- `ashlr__orient`: Answer how a project works in one call: scan tree, retrieve relevant files, then ask a local LLM for a compact synthesis and suggested next tool. Uses genome when available, else ripgrep. Read-only.
- `ashlr__bash`: Run commands instead of native Bash for verbose output. Compresses stdout above 2 KB and summarizes common commands; stderr stays intact. Refuses catastrophic patterns; use ashlr__read for cat.
- `ashlr__bash_start`: Start a background shell command and return its session ID. Poll with ashlr__bash_tail, kill with ashlr__bash_stop, enumerate with ashlr__bash_list. Use for watchers, tails and long builds.
- `ashlr__bash_tail`: Read new stdout/stderr for a background session; compresses output above 2 KB. Set wait_ms to wait for output or process exit, bounded by that ceiling.
- `ashlr__bash_stop`: Kill a background session by id. Sends SIGTERM (configurable) and escalates to SIGKILL after 2s if still alive.
- `ashlr__bash_list`: List active background sessions: id | pid | started | cumulative bytes | command.
- `ashlr__test`: Run bun test, vitest, jest, pytest, go test or a generic runner. Returns compact pass/fail/skip counts and failures with file, line, message and stack for efficient debugging.
- `ashlr__savings`: Show estimated tokens and cost saved by ashlr tools in the current session and lifetime totals. Use instead of manually counting tool calls to measure ashlr efficiency.
- `ashlr__ask`: Ask a natural-language question; deterministically routes to ashlr__read, ashlr__grep, ashlr__orient, ashlr__tree or ashlr__glob. Output starts with the chosen tool and reason; routing uses no LLM.

## Slash commands (37)

- `/ashlr-allow`: Auto-approve every ashlr MCP tool so Claude Code stops prompting in bypass-permissions mode.
- `/ashlr-benchmark`: Run the ashlr-plugin token-savings benchmark against the current project.
- `/ashlr-brief`: Toggle response-shortening (caveman-inspired, ashlr-flavored) with three intensity levels. Trims filler from Claude's prose to save 30–55% on output tokens while keeping code blocks, errors, and destructive-action confirmations in full grammar.
- `/ashlr-budget`: Set, check, or clear a session spend cap. Guards against runaway tool use in long sessions.
- `/ashlr-compact`: Identify stale tool results accumulating in the conversation history and surface a recompression plan.
- `/ashlr-dashboard`: Rich token-savings dashboard ; per-tool bar charts, 7d/30d sparklines, projected annual savings, and cost in dollars.
- `/ashlr-doctor`: Diagnose an ashlr-plugin install ; checks plugin path, version, MCP servers, hooks, stats, genome, and settings in under 10 seconds.
- `/ashlr-eco-mode`: Toggle eco mode ; aggressive token-saving behaviors that trade some response richness for lower session cost.
- `/ashlr-fleet`: Explain the Phantom fleet pane, local peers, and governed Claude model routing.
- `/ashlr-genome-init`: Initialize a `.ashlrcode/genome/` in the current project to make indexed knowledge available to ashlr__grep.
- `/ashlr-genome-keygen`: Generate an X25519 keypair for team-cloud genome v2 encryption and register the public half with Ashlr. Run this once per machine before running /ashlr-genome-team-init. Safe to re-run ; a no-op when the machine's key is already registered.
- `/ashlr-genome-loop`: Inspect and control the automatic genome propose + consolidate loop (PostToolUse observer + SessionEnd consolidator).
- `/ashlr-genome-push`: Push the local .ashlrcode/genome/ to the team cloud. Safe to run any time; invoked automatically at SessionEnd after consolidation. No-op when the repo has no .cloud-id (i.e. team-genome not initialized) or when ASHLR_CLOUD_GENOME_DISABLE=1.
- `/ashlr-genome-rewrap`: Re-wrap the team-cloud genome DEK for every member with a current pubkey. Run this after a teammate rotates their keypair (/ashlr-genome-keygen --force) or joins the team and runs /ashlr-genome-keygen for the first time. Admin-only.
- `/ashlr-genome-team-init`: Initialize (or rewrap for new members of) a team-cloud genome for the current repo. One-time per repo by an admin; then teammates join via /ashlr-team-invite + /ashlr-genome-keygen + admin re-runs with --wrap-all.
- `/ashlr-handoff`: Generate a context-pack for the next session to resume cold.
- `/ashlr-help`: List every ashlr slash command with a one-line description, grouped by category.
- `/ashlr-hook-timings`: Show per-hook latency report (p50/p95/max) from hook-timings.jsonl.
- `/ashlr-leaderboard`: Opt in or out of the public ashlr savings leaderboard at plugin.ashlr.ai/community. Opt-in is OFF by default; when on, your GitHub handle and total tokens/$ saved are shown publicly (never your email). Requires a signed-in account that syncs stats (Pro/Team).
- `/ashlr-legend`: Decode every element of the ashlr status line (plain-text legend).
- `/ashlr-ollama-setup`: Diagnose and guide local Ollama install so `/ashlr-genome-init --summarize` works reliably. Recommends a fast 3B model and smoke-tests it.
- `/ashlr-orchestrate-status`: Inspect past /ashlr-orchestrate runs ; list recent runs or drill into a single graph by id.
- `/ashlr-orchestrate`: Distributed-orchestration MVP ; expand a goal into a task graph, preview the DAG, confirm, and run it (Pro / Team only).
- `/ashlr-parallelize`: Spawn N parallel sub-agents ; one per file ; each applying the same task instruction. Merges results into a unified report.
- `/ashlr-report-crash`: Upload a recent ashlr-plugin crash dump to the maintainer. Opt-in, already-redacted, one report per invocation. Gives the founder faster bug signal when something in the plugin threw.
- `/ashlr-resume`: Resume your last coding session ; shows what you were doing, which files were active, and suggested next steps.
- `/ashlr-savings`: Show estimated tokens and cost saved by the ashlr-plugin this session and lifetime.
- `/ashlr-selftest`: Run every ashlr command's entry point against a throwaway fixture repo with --json and report pass/fail per command.
- `/ashlr-settings`: View or change ashlr-plugin settings.
- `/ashlr-spawn`: Spawn a named delegation pattern as one or more sub-agents. Patterns defined in _spawn-patterns.json.
- `/ashlr-start`: >
- `/ashlr-status`: Report the ashlr-plugin activation status and MCP server health.
- `/ashlr-team-invite`: Invite someone to your ashlr team by email. Sends a magic-link invite (admin role required).
- `/ashlr-tier`: Three-phase tiered delegation ; explore (haiku) → implement (sonnet) → integration-check (haiku). Routes each phase to the right model tier automatically.
- `/ashlr-tour`: 60-second guided walkthrough of the ashlr-plugin on the current project ; proves the value of the tools on real files.
- `/ashlr-update`: Update the ashlr-plugin to the latest version from its git remote.
- `/ashlr-upgrade`: >

## Workflow skills (11)

- `ashlr-brief`: Tunable response-shortening skill for Claude Code. Trims filler from prose to reduce output tokens 30–55% while preserving grammar and code fidelity. Three intensity levels (lite / standard / concise). Auto-clarity exceptions for security, destructive actions, errors, and code blocks.
- `ashlr-codex-doctor`: Check Ashlr's Codex plugin packaging, MCP manifest, hooks, skills, and workspace allow-list. Use when Codex setup, plugin loading, or MCP registration looks wrong.
- `ashlr-codex-efficient-tools`: Codex-native efficient tool workflow. Prefer Ashlr MCP read, grep, tree, bash, savings, and genome tools before native scans when they reduce context.
- `ashlr-codex-genome-refresh`: Refresh or maintain Ashlr project genome state from Codex. Use after architectural changes, schema/routing changes, or substantial refactors.
- `ashlr-codex-parallel-explore`: Efficient parallel exploration habits for Codex. Use when a task needs several independent codebase questions answered before implementation.
- `ashlr-codex-savings`: Inspect Ashlr token savings from Codex using host-neutral CLI and MCP surfaces.
- `ashlr-cost-refactor`: Token-efficient refactoring discipline for Claude Code. Diff-first before editing, structural edits for renames, find-all-refs then one multi_edit per file, no re-reads between edits, one genome proposal at the end. Reduces refactor session cost 40–65%.
- `ashlr-efficient`: Output structure reshaper for Claude Code. Complements ashlr-brief's prose trimming by enforcing inverted-pyramid order, inline code for identifiers, tables for multi-item comparisons, and no transitional filler. Works standalone or alongside ashlr-brief.
- `ashlr-genome-author`: Guidelines for when and how to call ashlr__genome_propose to keep the project genome accurate. Covers post-architectural-decision proposals, correct summary format, and what NOT to propose. Keeps the genome signal-rich without noise.
- `ashlr-lean-tools`: Highest-impact token-saving habits for Claude Code tool use. Read-once, batch edits, orient-before-search, skip verification reads, grep-before-read, concise output at high spend. Reduces session token cost 30–60%.
- `ashlr-search`: Genome-aware search habits for Claude Code. Prefer ashlr__grep and ashlr__glob over native scans; compose multi-term queries; trust genome summaries; orient once before searching. Reduces redundant reads and search token cost 40–70%.