ashlr-plugin 1.36.4

package/docs/launch/hn.md

@@ -0,0 +1,49 @@
+# Hacker News launch post — v1.36 Codex-native release
+
+## Title options
+
+- Show HN: Ashlr — open-source Codex and Claude Code plugin, −57% tokens
+- Show HN: Ashlr — token-efficient MCP tools for Codex and Claude Code
+- Show HN: 40 MCP tools that compress AI coding context
+
+## URL
+
+https://plugin.ashlr.ai/
+
+## First comment
+
+Hi HN. I built Ashlr after watching AI coding sessions spend a lot of context on file I/O the model did not actually need: full file reads, full grep output, verbose shell logs, and edit payloads that echo too much surrounding state.
+
+Ashlr is an open-source MCP/plugin layer for Codex, Claude Code, Cursor, Goose, and generic MCP hosts. It ships 40 MCP tools. The high-volume ones are lower-token alternatives for read, grep, edit, bash, tree, logs, diff, SQL, HTTP, GitHub PR/issue reads, and project genome retrieval.
+
+The current release is Codex-native:
+
+- `.codex-plugin/plugin.json`
+- `.mcp.json`
+- Codex workflow skills
+- Codex explorer/worker guidance
+- nudge-first Codex hooks
+
+Claude Code remains supported with slash commands, status line, and redirect-mode hooks. Cursor and Goose use the MCP server directly.
+
+The benchmark headline is −57% cross-repo token savings:
+
+- TypeScript (`vercel/ai`): −62%
+- Python (`pandas`): −65%
+- Rust (`tokio`): −44%
+
+The methodology is public in `docs/benchmarks.md`; the benchmark runner is in `scripts/run-benchmark.ts`.
+
+Ethics/ops: MIT license, no account required, telemetry off by default, no code/path/prompt telemetry in the default setup. Pro features are hosted genome sync and hosted summarization; the local MCP tool surface remains free.
+
+Install:
+
+```sh
+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
+```
+
+Repo: https://github.com/ashlrai/ashlr-plugin

package/docs/launch/reddit.md

@@ -0,0 +1,45 @@
+# Reddit launch posts — v1.36 Codex-native release
+
+## r/codex or r/ClaudeCode title
+
+**ashlr v1.36 — open-source Codex + Claude Code efficiency layer, 40 MCP tools, −57% measured token savings**
+
+## Body
+
+I shipped the Codex-native Ashlr release.
+
+Ashlr is an open-source MCP/plugin layer that reduces token waste from high-volume AI coding workflows: file reads, grep output, shell logs, edit summaries, directory trees, diffs, SQL output, HTTP fetches, GitHub PR/issue reads, and project memory retrieval.
+
+What ships now:
+
+- 40 MCP tools
+- Codex plugin manifest in `.codex-plugin/`
+- Codex MCP config in `.mcp.json`
+- Codex workflow skills and explorer/worker guidance
+- Codex nudge-first hooks
+- Claude Code slash commands, status line, and redirect hooks
+- Cursor and Goose MCP ports
+
+The benchmark is reproducible and uses TypeScript, Python, and Rust reference repos:
+
+- TypeScript (`vercel/ai`): −62%
+- Python (`pandas`): −65%
+- Rust (`tokio`): −44%
+- Cross-language mean: −57%
+
+Install:
+
+```sh
+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
+```
+
+Claude Code users can run the installer, then the marketplace slash commands.
+
+MIT, no account required, telemetry off by default. Pro adds hosted infrastructure; the local MCP tool surface remains free.
+
+Landing: https://plugin.ashlr.ai/
+Repo: https://github.com/ashlrai/ashlr-plugin

package/docs/launch/x.md

@@ -0,0 +1,65 @@
+# X / Twitter launch post — v1.36 Codex-native release
+
+## Main thread
+
+**1/**
+Codex and Claude Code sessions burn tokens on file I/O: full reads, full grep output, verbose shell logs, and before/after edit payloads.
+
+ashlr is an open-source efficiency layer that compresses those workflows instead of shipping the whole payload every time.
+
+**Measured cross-repo savings: −57%.**
+
+---
+
+**2/**
+v1.36 ships:
+
+- 40 MCP tools
+- Codex plugin manifest in `.codex-plugin/`
+- Codex MCP config in `.mcp.json`
+- Codex workflow skills
+- Codex nudge-first hooks
+- Claude Code slash commands, redirects, and status line
+- Cursor and Goose MCP ports
+
+---
+
+**3/**
+The benchmark is reproducible:
+
+- TypeScript (`vercel/ai`): −62%
+- Python (`pandas`): −65%
+- Rust (`tokio`): −44%
+- Cross-language mean: −57%
+
+Methodology is public in `docs/benchmarks.md`.
+
+---
+
+**4/**
+The free tier is not crippled.
+
+MIT license. No account required. Telemetry off by default. Stats stay local unless you explicitly enable hosted features.
+
+Pro adds cloud genome sync and hosted summarization; the 40 MCP tools remain free.
+
+---
+
+**5/**
+Install:
+
+```sh
+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
+```
+
+Claude Code users can run the installer, then the marketplace slash commands.
+
+plugin.ashlr.ai
+
+## Standalone single post
+
+Open-source Codex + Claude Code efficiency layer: 40 MCP tools, Codex skills, nudge-first Codex hooks, Claude Code slash commands/status line, and measured −57% cross-repo token savings. MIT, no account required, telemetry off by default. plugin.ashlr.ai

package/docs/launch-post.md

@@ -0,0 +1,112 @@
+# Why I built a token-efficiency layer for Codex and Claude Code
+
+Token counts are a real operating cost. I started noticing it the same way you notice a slow memory leak: not all at once, but through accumulating evidence. The context window fills up faster than it should. Sessions hit the limit mid-refactor. The Anthropic invoice climbs past what feels proportionate to the actual work done.
+
+The culprit is usually reads. When an AI coding agent opens a 15,000-token file to change three lines, it can ship all 15,000 tokens to the model as context. Grep a large codebase for an import pattern and you might get 85,000 tokens of match output that the model skims and discards. Every native `Read`, `Grep`, and `Edit` call transmits the full payload whether the model needs it or not.
+
+That is the problem ashlr solves.
+
+---
+
+## What it is
+
+ashlr is an open-source Codex and Claude Code efficiency layer: 40 MCP tools, Codex skills, 34 Claude Code slash commands, an optional Claude status line, and an optional hosted backend. One-line Claude Code install:
+
+```bash
+curl -fsSL https://plugin.ashlr.ai/install.sh | bash
+```
+
+The tools replace high-volume `Read`, `Grep`, `Edit`, and `Bash` workflows with compressed alternatives. `ashlr__read` returns a head+tail snip instead of the full file. `ashlr__grep` routes through a genome-aware retrieval index when one exists, and falls back to truncated ripgrep otherwise. `ashlr__edit` returns a diff summary instead of echoing the full before+after. The model gets enough context to do the work. The bill shrinks.
+
+---
+
+## Why now
+
+Two things converged. Claude Code and Codex both expose plugin/MCP surfaces, which means tools like this can run as standard MCP servers under compatible hosts — Codex packaging, Cursor, and Goose ports ship with the plugin today. And AI coding costs have matured from "toy" to "line item." Teams running AI coding agents across five engineers with heavy usage are spending real money. The efficiency question is no longer academic.
+
+---
+
+## The moment it clicked
+
+I was working in this repo — the ashlr-plugin codebase itself, 750 files, 149,462 lines — and ran a benchmark to see what the numbers actually looked like. Not rough estimates. Measured, reproducible numbers against real files.
+
+Here is what the benchmark found on `ashlr__read` for a 15KB test file (`server/tests/auth.test.ts`, 10,846 bytes):
+
+| | Raw | ashlr |
+|---|---|---|
+| Bytes | 10,846 | 1,623 |
+| Tokens | 2,709 | 406 |
+| Ratio | 1.00 | 0.15 |
+
+That is an 85% reduction on one file. For the `CHANGELOG.md` (41,100 bytes, 10,200 raw tokens), the ratio drops to 0.040 — the compressed view uses 406 tokens where the full file would have used 10,200. The model gets the structural information it needs; the padding disappears.
+
+Across all file sizes in the benchmark:
+
+| Tool | Mean savings | p50 savings |
+|---|---|---|
+| `ashlr__read` | −82.2% | −88.8% |
+| `ashlr__grep` | −81.7% | −97.2% |
+| **Overall** | **−57%** | — |
+
+The overall −57% is the cross-language headline across TypeScript, Python, and Rust reference repos. The benchmark methodology is published in `docs/benchmarks.md` and `docs/benchmarks-v2.json`.
+
+---
+
+## What's free, what's paid
+
+Everything in the free tier is the product. 40 MCP tools, 34 Claude Code slash commands, Codex workflow skills, the genome scribe loop, per-session token accounting, a calibration harness, a reproducible benchmark. MIT license. No account. Telemetry off by default.
+
+Pro ($12/month or $120/year) adds hosted infrastructure for developers who need it: a cloud LLM summarizer so you do not need Ollama running locally, cross-machine stats sync, a live auto-updating badge. It does not remove or degrade anything in the free tier.
+
+Team ($24/user/month) adds the shared encrypted team genome — one authoritative retrieval index per repo, end-to-end encrypted with AES-256-GCM and synced via vclock-based last-write-wins (concurrent edits surface in `/ashlr-genome-conflicts` for a one-click manual resolve) — plus org dashboards, policy packs, genome diffs on PRs, SSO, and audit log.
+
+Enterprise covers on-prem deployment with private inference. Nothing about the free tier is crippled to push upgrades.
+
+---
+
+## Who it's for
+
+Individual developers today. If you use Codex or Claude Code heavily on real codebases, the free tier will measurably reduce your token consumption within the first session. Run `bun run scripts/run-benchmark.ts --compare` to measure your repo. In Codex sessions, inspect live savings after Ashlr tool calls with `ashlr stats --json` or `ashlr__savings`; in Claude Code, use `/ashlr-benchmark` or `/ashlr-savings`.
+
+Teams via pro. The shared genome becomes worth the overhead at three or more engineers working the same codebase — the retrieval index reflects everyone's edits, not just yours.
+
+Enterprise via on-prem. If your company is sensitive about code leaving the VPC, the plugin's architecture supports private inference endpoints. The genome format is a public spec; nothing is locked to the hosted service.
+
+---
+
+## Three things that surprised me building this
+
+**The session counter bug (v0.9.3).** The status line was showing `session +0` for many users even as lifetime totals kept climbing. The cause was subtle: Claude Code forwards `CLAUDE_SESSION_ID` to hooks but not to MCP server subprocesses. So the MCP server was writing savings to a PPID-hash bucket, and the status line was reading a `CLAUDE_SESSION_ID` bucket, and the two never intersected. The fix — `candidateSessionIds()` returning both and aggregating across them — sounds obvious in retrospect but required actually inspecting a live `stats.json` to see the orphaned bucket sitting there with 2,863 tokens that nobody was reading.
+
+**The `$` interpolation bug (v0.9.2).** `ashlr__multi_edit` uses `String.prototype.replace()` for strict-mode edits. JavaScript's `replace(string, string)` interprets `$&`, `$1`, `` $` ``, and `$'` in the replacement string. This silently corrupted any edit whose replacement contained a `$` followed by certain characters — template literals, TypeScript generic constraints, currency strings. The fix was switching to `slice + concat`, which treats the replacement as a literal. The bug had been there since the tool launched; the security audit in v0.9.2 caught it.
+
+**Zombie processes (v1.0.1).** Running `/reload-plugins` in Claude Code re-reads plugin manifests but does not kill MCP server subprocesses spawned by earlier reloads. If a terminal was opened before an upgrade, the old MCP server process keeps writing the old stats.json schema alongside the new writers. The v1 and v2 shapes are incompatible enough that the v1 writer was periodically wiping the `sessions` map that the v2 reader depended on. The fix was a fallback in `pickSession()` that surfaces the v1 singular counter when the v2 sessions map is empty. Full correctness requires restarting Claude Code, not just reloading plugins.
+
+---
+
+## Open source
+
+The full plugin — every tool, every skill, the genome format, the compression logic — is on GitHub at [github.com/ashlrai/ashlr-plugin](https://github.com/ashlrai/ashlr-plugin). The benchmark script is `scripts/run-benchmark.ts` and the seeded results are in `docs/benchmarks-v2.json`. The CI job at `.github/workflows/ci.yml` runs it on every push and opens a PR on Monday to refresh the data.
+
+860 tests pass. 2 are skipped: a `no-genome grep` flake that only surfaces in the full-suite parallel environment (passes reliably in isolation) and a benchmark ratio assertion with the same root cause. Both are documented in-line.
+
+---
+
+## Install
+
+```bash
+curl -fsSL https://plugin.ashlr.ai/install.sh | bash
+```
+
+Then inside Claude Code:
+
+```
+/plugin marketplace add ashlrai/ashlr-plugin
+/plugin install ashlr@ashlr-marketplace
+```
+
+Restart Claude Code. Run `/ashlr-allow` once to silence permission prompts. Run `/ashlr-tour` for a 60-second walkthrough on your actual codebase.
+
+Full docs at [plugin.ashlr.ai/docs](https://plugin.ashlr.ai/docs). Pricing at [plugin.ashlr.ai/pricing](https://plugin.ashlr.ai/pricing).
+
+If the numbers look wrong on your codebase, run `/ashlr-benchmark` and open an issue. The methodology is public and the script is auditable.

package/docs/legal.md

@@ -0,0 +1,78 @@
+# Pre-launch Legal Checklist
+
+Internal tracking doc. Do not publish.
+
+Last reviewed: 2026-04-18
+
+---
+
+## Before launch — required actions
+
+### Entity and policy text
+
+- [x] **Entity name confirmed.** Privacy, Terms, and DPA now say "AshlrAI Inc" (Delaware corporation). Contact email is `support@ashlr.ai` across all pages.
+- [x] **Governing law clause.** Delaware, in `site/app/terms/page.tsx` section 10. Placeholder removed.
+- [ ] **Data residency claims.** Privacy Policy section 8 states "US-East (iad)" for Fly.io and Neon. Verify this matches the actual region in `fly.toml` and the Neon project settings before go-live.
+- [ ] **Age verification.** Both Privacy Policy (section 9) and Terms (section 3) set a 13+ minimum. If you ever target education or government markets you may need FERPA/COPPA review.
+
+### Stripe
+
+- [ ] Register and verify the Stripe webhook endpoint (`/api/stripe/webhook`) with the correct signing secret in your production environment.
+- [ ] Enable the billing portal in the Stripe dashboard (Settings → Billing → Customer portal) so the "cancel anytime via portal" promise in Terms section 5 actually works.
+- [ ] Confirm the 14-day refund window is noted in the Stripe portal configuration.
+- [ ] Confirm tax collection settings (automatic tax or manual) match the "exclusive of taxes" language in Terms section 5.
+
+### SendGrid
+
+- [ ] Verify the sending domain (`ashlr.ai`) in the SendGrid dashboard. Add SPF, DKIM, and DMARC records to DNS.
+- [x] `support@ashlr.ai` is the canonical contact email — referenced across privacy, terms, DPA, pricing, footer, docs, and docs/pro/*.
+- [ ] Set up transactional email templates: welcome / magic link, subscription receipt, renewal reminder, policy change notice (30-day lead).
+
+### Sub-processor DPAs
+
+If you sign enterprise customers, you will need countersigned DPAs with each sub-processor:
+
+- [ ] Railway — check their DPA availability at https://railway.com/legal/dpa
+- [ ] Neon — check their DPA availability at https://neon.tech/legal
+- [ ] Vercel — DPA available at https://vercel.com/legal/dpa
+- [ ] Stripe — DPA available at https://stripe.com/legal/dpa
+- [ ] SendGrid — DPA at https://www.twilio.com/en-us/legal/data-protection-addendum (Twilio SendGrid)
+
+### International
+
+- [ ] If you have EU enterprise customers, ensure Fly.io and Neon projects can be migrated to EU regions as promised in Privacy Policy section 8 and DPA section 3.
+- [ ] Confirm SCC module selection (Module 2: controller-to-processor) with each sub-processor DPA.
+- [ ] UK adequacy — if you have UK customers post-Brexit, SCCs with UK addendum (IDTA) may be required.
+
+---
+
+## What's low-risk (can launch as-is)
+
+- Cookie notice — minimal cookies (Stripe on checkout only), banner is accessible and stores consent in localStorage for 180 days.
+- CCPA compliance — we collect no data on the free tier; Pro collects only email and aggregate numbers. No sale of data. The DPA stub correctly states this.
+- MIT license / IP section — straightforward, no legal risk.
+- Limitation of liability cap (12 months fees or $100 minimum) — standard SaaS clause, low risk for a developer tool.
+- Arbitration clause — AAA rules, Delaware seat, standard for US-based SaaS.
+- Children's policy (13+) — conservative threshold, no COPPA complexity.
+
+---
+
+## What needs legal review before enterprise sales
+
+- Governing law and arbitration (sections 10–11 of Terms) — confirm state of formation.
+- DPA countersignature process — the `/dpa` page is a stub; a proper exhibit needs to be drafted and signed for each enterprise customer.
+- 99.5% SLA for enterprise — only commit to this if you have monitoring and runbook in place.
+- GDPR Article 37 DPO assessment — currently stated as not required. Revisit if EU revenue exceeds thresholds or if you process special categories of data.
+
+---
+
+## File locations
+
+| Document | Route | File |
+|---|---|---|
+| Privacy Policy | /privacy | site/app/privacy/page.tsx |
+| Terms of Service | /terms | site/app/terms/page.tsx |
+| Data Processing Addendum | /dpa | site/app/dpa/page.tsx |
+| Cookie banner component | (component) | site/components/cookie-banner.tsx |
+| Footer (updated) | (component) | site/components/footer.tsx |
+| Sitemap | /sitemap.xml | site/app/sitemap.ts |

package/docs/llm-providers.md

@@ -0,0 +1,99 @@
+# LLM Provider Hierarchy
+
+ashlr's summarization layer picks the best available LLM automatically. This doc explains the hierarchy, env vars, and costs.
+
+## Provider order (`ASHLR_LLM_PROVIDER=auto`)
+
+```
+anthropic  →  onnx  →  local  →  none (truncation fallback)
+```
+
+Each provider is tried in order. The first one whose `isAvailable()` returns true is used for the session. If a provider's `summarize()` throws at runtime, the output falls back to `snipCompact` truncation (never crashes, never blocks).
+
+## Providers
+
+### anthropic (default winner)
+
+**Model:** `claude-haiku-4-5-20251001`
+
+**Availability:** `ANTHROPIC_API_KEY` env var, OR Claude Code's credential store at `~/.claude/.credentials.json` (written automatically when you log in to Claude Code — no extra setup needed).
+
+**Cost:** $0.80/MTok input + $4.00/MTok output. A typical 16KB→500-byte summarization uses ~4K in + ~500 out ≈ $0.005.
+
+**Timeout:** 15 seconds per call.
+
+### onnx (stubbed in v1.22)
+
+**Model:** Xenova/distilbart-cnn-6-6 (text summarization, ~300MB)
+
+**Status:** Stubbed. `isAvailable()` always returns false in this release. Model files can be pre-downloaded with:
+
+```bash
+bun run scripts/install-onnx-model.ts
+```
+
+The inference pipeline will be wired in a future sprint. Once available, ONNX runs fully offline at $0 cost.
+
+**Availability when implemented:** `onnxruntime-node` installed (optional dep) AND model at `~/.ashlr/models/distilbart/`.
+
+### local
+
+Connects to an OpenAI-compatible server (LM Studio, Ollama, etc.).
+
+**Availability:** Pings `GET {ASHLR_LLM_URL}/models` — responds 200 within 2s. Result cached for 60s.
+
+**Env vars:**
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `ASHLR_LLM_URL` | `http://localhost:1234/v1` | Base URL of the local server |
+| `ASHLR_LLM_KEY` | `local-llm` | Bearer token (most local servers don't validate) |
+| `ASHLR_LLM_MODEL` | `qwen/qwen3-coder-30b@8bit` | Model name to request |
+
+**Cost:** $0 (local inference).
+
+### none
+
+Selected when no other provider is available. `summarize()` throws immediately, and the caller falls back to `snipCompact` truncation with an `[ashlr · LLM unreachable, fell back to truncation]` note.
+
+## Controlling provider selection
+
+```bash
+# Env var (set in shell profile or .env)
+export ASHLR_LLM_PROVIDER=auto        # default: try each in order
+export ASHLR_LLM_PROVIDER=anthropic   # force Anthropic; throw if unavailable
+export ASHLR_LLM_PROVIDER=local       # force local LM Studio / Ollama
+export ASHLR_LLM_PROVIDER=off         # disable summarization entirely
+```
+
+## Telemetry
+
+Every summarization call emits a `llm_summarize_provider_used` event to `~/.ashlr/session-log.jsonl`:
+
+```jsonl
+{"ts":"...","event":"tool_call","tool":"ashlr__read","provider":"anthropic","latency_ms":342,"in_tokens":4096,"out_tokens":487,"fellBackToSnipCompact":false,"llmCostUsd":0.00523}
+```
+
+Use `/ashlr-savings` or `/ashlr-dashboard` to view aggregated stats.
+
+## Diagnosing provider selection
+
+```bash
+/ashlr-doctor
+```
+
+The "runtime state" section reports which provider would be selected and any availability issues.
+
+## Architecture
+
+Implementation lives in `servers/_llm-providers/`:
+
+| File | Purpose |
+|------|---------|
+| `types.ts` | `LlmProvider` interface |
+| `anthropic.ts` | Anthropic Haiku 4.5 via Messages API |
+| `onnx.ts` | ONNX local inference (stubbed) |
+| `local.ts` | OpenAI-compat local LLM |
+| `index.ts` | `selectProvider()` + `summarizeIfLarge()` facade |
+
+`servers/_summarize.ts` re-exports `summarizeIfLarge` from `index.ts` — all existing callers are unchanged.

package/docs/multi-host-mcp.md

@@ -0,0 +1,217 @@
+# Multi-host MCP setup
+
+`ashlr-plugin` ships its 40 efficiency tools as a single MCP stdio server. The
+server is host-agnostic — any client that speaks the [Model Context Protocol](https://modelcontextprotocol.io/)
+can wire it up. Savings and accounting apply when the host calls Ashlr MCP
+tools: Claude Code redirects automatically, Codex nudges toward those tools,
+and other hosts call them directly.
+
+| Host                  | Status     | Hook redirects | Status line | Slash commands |
+| --------------------- | ---------- | -------------- | ----------- | -------------- |
+| **Claude Code**       | ✅ Default | ✅ yes         | ✅ yes      | ✅ yes         |
+| **Cline (OSS)**       | ✅ Working | ❌ no (1)      | ❌ no       | n/a            |
+| **Claude Desktop**    | ✅ Working | ❌ no (1)      | ❌ no       | n/a            |
+| **OpenAI Codex CLI**  | ✅ First-class plugin | ✅ nudge-first | ❌ no       | skills         |
+| **Cursor**            | ✅ Working MCP port | ❌ no (1)      | ❌ no       | n/a            |
+| **Goose**             | ✅ Working recipe | ❌ no (1)      | ❌ no       | n/a            |
+| **Generic MCP host**  | ✅ Working | ❌ no (1)      | ❌ no       | n/a            |
+
+> (1) Hook redirects (`ASHLR_HOOK_MODE=redirect` that auto-rewrites the host's
+> built-in `Read`/`Grep`/`Edit` to `ashlr__*`) are Claude-Code-specific because
+> they rely on Claude Code's PreToolUse hook system. On other hosts you call
+> `ashlr__read` / `ashlr__grep` / `ashlr__edit` directly. Same tools, same
+> savings, one extra prefix.
+>
+> Codex is the exception: it ships a separate nudge-first hook manifest at
+> `hooks/codex-hooks.json`. Codex hooks inject `additionalContext` by default
+> and keep native tool calls allowed.
+
+## Portable retrieval guidance
+
+Every MCP initialize response includes the same short efficiency instructions,
+regardless of host. Start with structure and targeted searches, then retrieve the
+source needed for the task. Compacted results guide retrieval: omitted source
+must be read before an edit or verification relies on it. Requirements,
+AGENTS.md, authorization, citations, exact errors and test evidence remain
+required context. The server neither rewrites host prompts nor changes approval
+policy. This improves portable tool use; it does not establish universal token
+savings or model quality.
+
+## How host detection works
+
+Every host's MCP server config sets the env var `ASHLR_MCP_HOST` so the
+server knows where it's running:
+
+```
+ASHLR_MCP_HOST=claude-code    # default — preserved for back-compat
+ASHLR_MCP_HOST=cline
+ASHLR_MCP_HOST=claude-desktop
+ASHLR_MCP_HOST=codex-cli
+ASHLR_MCP_HOST=generic        # safe default for anything else
+```
+
+If the env var is missing, the server infers `claude-code` when it sees
+`CLAUDE_SESSION_ID` / `CLAUDE_PLUGIN_ROOT` / `CLAUDE_CODE_MODEL`, and
+`generic` otherwise. The startup banner echoes the resolved host:
+
+```
+[ashlr-router] starting · 40 tools registered · version=1.29.0 · host=cline
+```
+
+## Cline (cline_mcp_settings.json)
+
+Cline's MCP config lives in your OS-specific Cline settings dir (see
+[Cline MCP docs](https://github.com/cline/cline/blob/main/docs/mcp/README.md)).
+The file is typically at:
+
+- macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+- Linux: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+- Windows: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+
+Add this `mcpServers` entry (replace `/abs/path/to/ashlr-plugin` with where
+you cloned the repo):
+
+```json
+{
+  "mcpServers": {
+    "ashlr": {
+      "command": "bun",
+      "args": ["run", "/abs/path/to/ashlr-plugin/scripts/ashlr-mcp.ts"],
+      "env": {
+        "ASHLR_MCP_HOST": "cline"
+      }
+    }
+  }
+}
+```
+
+Restart Cline. The tool palette will surface `ashlr__read`, `ashlr__grep`,
+`ashlr__edit`, `ashlr__bash`, `ashlr__savings`, and 35 others.
+
+**Don't have Bun?** Use the node trampoline instead — it auto-installs Bun
+on first run:
+
+```json
+{
+  "command": "node",
+  "args": ["/abs/path/to/ashlr-plugin/scripts/bootstrap.mjs", "servers/_router.ts"],
+  "env": { "ASHLR_MCP_HOST": "cline" }
+}
+```
+
+## Claude Desktop (claude_desktop_config.json)
+
+Claude Desktop reads `~/Library/Application Support/Claude/claude_desktop_config.json`
+on macOS (and the equivalent `%APPDATA%\Claude\claude_desktop_config.json` on
+Windows). Add:
+
+```json
+{
+  "mcpServers": {
+    "ashlr": {
+      "command": "bun",
+      "args": ["run", "/abs/path/to/ashlr-plugin/scripts/ashlr-mcp.ts"],
+      "env": {
+        "ASHLR_MCP_HOST": "claude-desktop"
+      }
+    }
+  }
+}
+```
+
+Quit and reopen Claude Desktop. The tool count appears next to the input box.
+
+## OpenAI Codex CLI (~/.codex/config.toml)
+
+Codex can install Ashlr as a plugin from `.codex-plugin/plugin.json`, or use
+the MCP-only TOML config below. The repo-local plugin also includes `.mcp.json`,
+`hooks/codex-hooks.json`, Codex skills under `skills/`, and explorer/worker
+agent guidance under `.codex/agents/`.
+
+Codex CLI's MCP config uses TOML. Add this block to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.ashlr]
+command = "bun"
+args = ["run", "/abs/path/to/ashlr-plugin/scripts/ashlr-mcp.ts"]
+env = { ASHLR_MCP_HOST = "codex-cli" }
+```
+
+Run `codex` — the tools register on startup. If Codex launches the MCP server
+from outside your workspace, either pass `cwd` arguments to Ashlr tools or set
+`ASHLR_ALLOW_PROJECT_PATHS=/abs/path/to/project` in the MCP env.
+
+For a dry-run config plan:
+
+```bash
+bun run scripts/cli.ts codex-install --dry-run --json
+bun run scripts/cli.ts codex-doctor --json
+```
+
+## Generic MCP host
+
+Any MCP-capable client (in-house tooling, experimental hosts, …) can speak
+to the ashlr server over stdio. Spawn it directly:
+
+```bash
+ASHLR_MCP_HOST=generic bun run /abs/path/to/ashlr-plugin/scripts/ashlr-mcp.ts
+```
+
+The server speaks JSON-RPC 2.0 on stdin/stdout. Send `initialize` →
+`tools/list` → `tools/call` per the MCP spec. The server emits its
+startup banner on stderr (won't interfere with stdio protocol).
+
+## What works in every host
+
+These features are host-agnostic and Just Work everywhere:
+
+- **All 40 MCP tools** — `ashlr__read`, `ashlr__grep`, `ashlr__edit`, plus
+  the bash, http, sql, github, genome, and orchestration families.
+- **Stats accounting** — writes to `~/.ashlr/stats.json` regardless of
+  host. `ashlr-plugin stats --json` CLI works everywhere Bun runs.
+- **Genome retrieval** — `.ashlrcode/genome/` lookups work identically.
+  Cloud-genome sync requires Pro/Team auth (see limitations below).
+- **Telemetry consent** — `ASHLR_TELEMETRY_OPT_IN=1` honored identically.
+  No host ever auto-enables it.
+- **Per-handler crash isolation** — one tool throwing won't kill the
+  process. Stack traces redirect to `~/.ashlr/crash-dumps/`.
+
+## What doesn't work outside Claude Code (and why)
+
+These are Claude-Code-specific surfaces. Other hosts have their own
+conventions; we don't try to fight them.
+
+- **Claude hook redirects** — declared in `hooks/hooks.json` and default to
+  redirect mode for Claude Code. Codex uses `hooks/codex-hooks.json` instead,
+  defaults to `additionalContext` nudges, and keeps tool calls allowed.
+- **Slash commands** (`/ashlr-doctor`, `/ashlr-savings`, …) — these are
+  Claude Code prompt-templates in `commands/*.md`. Other hosts don't have
+  an equivalent surface. The same diagnostics live in the `ashlr-plugin` CLI
+  (`ashlr-plugin stats --json`, `ashlr-plugin tools`, `ashlr-plugin version`).
+- **Status line** (the `−$X` savings ticker) — Claude Code's `statusLine`
+  manifest extension. Other hosts render their own footer.
+- **Pro/Team auth** — currently bootstrapped from
+  `~/.claude/.credentials.json` (the OAuth token Claude Code stores after
+  `/login`). Non-CC users can set `ANTHROPIC_API_KEY` for LLM summarization;
+  Pro/Team sign-in via `/ashlr-upgrade` is Claude-Code-only until a
+  host-agnostic auth flow lands. Use `ASHLR_PRO_ASSUME=1` for trial-style
+  unlock if you've already activated Pro on this machine via Claude Code.
+
+## Troubleshooting
+
+**"command not found: bun" when launching the MCP server**
+Install Bun once: `curl -fsSL https://bun.sh/install | bash` (or use the
+node trampoline shown above — it auto-installs Bun on first invocation).
+
+**Tools register but every call returns "no stats yet"**
+Stats are written on tool _call_, not on registration. Run any `ashlr__*`
+tool from your host once, then `ashlr-plugin stats --json` will return data.
+
+**Session counter stuck at 0 across hosts**
+The PPID-derived fallback session id is per-process. Different hosts spawn
+the MCP server with different PIDs → different session buckets. That's
+expected. The lifetime totals are still globally accurate.
+
+**Want the hook-based auto-redirect feel in Cline?**
+File an issue — we're tracking interest in a Cline-native equivalent
+that uses Cline's pre-tool-execution hooks (when those land upstream).