Environment variables reference
Complete reference for all ASHLR_* environment variables — defaults, purpose, and which component reads each one.
All runtime behavior in ashlr-plugin can be tuned through environment variables. Set them in your shell profile, .env, or directly before the MCP entrypoint command. None are required for basic operation.
Core behavior
| Variable | Default | Description |
|---|---|---|
ASHLR_HOOK_MODE | redirect | PreToolUse hook behavior. redirect — intercept native Read/Grep/Edit and deny with "use ashlr__* instead". nudge — print a suggestion but allow the native call. off — hooks fire but do nothing. |
ASHLR_ROUTER_DISABLE | unset | Set to 1 to revert to legacy per-server mode (kill-switch, one release cycle only). |
ASHLR_MCP_HOST | generic via CLI launchers | MCP host identifier. Set explicitly to claude-code, codex-cli, cursor, cline, claude-desktop, gemini-cli, or generic. A directly launched router can infer Claude Code from nonempty Claude environment signals when this is unset. Affects host-specific side effects. |
ASHLR_CODEX_HOOK_MODE | nudge | Codex hook behavior. nudge injects additionalContext, off disables Codex nudges, and redirect is reserved for proven redirect-compatible hooks. |
ASHLR_DEBUG | unset | Any nonempty value prints extra diagnostics to stderr from the SQLite stats backend (ASHLR_STATS_BACKEND=sqlite) and the benchmark reference script. Other servers do not read it. |
ASHLR_VERSION | (from plugin.json) | Override the reported version string. |
ASHLR_PHANTOM_PREFLIGHT | unset | Set to 1 (or true, on) to make the doctor also run Phantom's value-free phantom agent doctor --json --strict: blocked fails, degraded or unknown warns. strict fails on anything but ready. A missing phantom is only a warning. See docs/phantom-preflight.md. |
Hooks
| Variable | Default | Description |
|---|---|---|
ASHLR_TASK_PASSTHROUGH | unset | Set to 1 to let native TaskList and TaskGet through instead of redirecting them to ashlr__task_list and ashlr__task_get. |
ASHLR_EDIT_MIN_CHARS | 80 | Minimum combined length of old_string and new_string before the Edit hook redirects to ashlr__edit. Smaller edits pass through to native Edit. |
ASHLR_ENFORCE | unset | Legacy. Set to 1 to make the Read, Grep and Edit hooks block with exit code 2 and a stderr message, independent of ASHLR_HOOK_MODE. |
ASHLR_NO_ENFORCE | unset | Set to 1 to turn off the legacy ASHLR_ENFORCE=1 blocking. |
ASHLR_HOOK_TIMEOUT_MS | 2000 | Safety-net timeout for each hook process. A hook that runs longer exits 0 so it never blocks the tool call. |
ASHLR_HOOK_TIMINGS | on | Set to 0 to stop writing ~/.ashlr/hook-timings.jsonl, the data behind /ashlr-hook-timings. |
ASHLR_BLOCK_WINDOW_MS | 10000 | How long after a redirected native call a matching ashlr__* call still counts as converted in the session log. |
ASHLR_PERMISSIONS_CONSENT | unset | Set to skip so the session-start hook never adds the ashlr tool wildcard to the Claude Code allow list. |
ASHLR_QUIET | unset | Set to 1 to silence the session-start greeting (welcome box, last-session savings line and weekly summary). Session state is still recorded. |
ASHLR_NO_GREET | unset | Set to 1 to skip the session-start greeting but keep its state updates. |
Edit tools
| Variable | Default | Description |
|---|---|---|
ASHLR_EDIT_FUZZY | on | Set to off to stop ashlr__edit and ashlr__multi_edit from falling back to a confident, unique fuzzy match when a strict search has no exact match (files up to 2 MB). |
ASHLR_EDIT_VALIDATE | unset | Set to block to refuse an edit that introduces a syntax error. By default such an edit is still written. |
Storage paths
| Variable | Default | Description |
|---|---|---|
ASHLR_HOME_OVERRIDE | $HOME | Home directory that contains .ashlr/ (stats.json, session-log.jsonl, caches). Intended for tests and sandboxes; normal installs leave it unset. |
ASHLR_SESSION_LOG | unset | Set to 0 to stop writing ~/.ashlr/session-log.jsonl and session events. It is a kill switch, not a path. |
ASHLR_STATS_BACKEND | json | Stats storage backend. json uses ~/.ashlr/stats.json. sqlite uses ~/.ashlr/stats.db (SQLite, lower contention under heavy parallel load). |
ASHLR_STATS_DB_PATH | ~/.ashlr/stats.db | Path to the SQLite DB when ASHLR_STATS_BACKEND=sqlite. |
ASHLR_CONTEXT_DB_DISABLE | unset | Set to 1 to disable the SQLite context tracking DB. |
Session accounting
| Variable | Default | Description |
|---|---|---|
ASHLR_SESSION_ID | (from CLAUDE_SESSION_ID) | Session bucket key. Inherited from the Claude Code harness. Override to isolate test sessions. |
ASHLR_PRICING_MODEL | sonnet-4.6 | Model used to compute cost savings. When unset, ashlr uses CLAUDE_CODE_MODEL (with any claude- prefix removed) and then sonnet-4.6. Options: sonnet-4.6, sonnet-4.5, opus-4.7, opus-4, haiku-4.5. Unknown names fall back to sonnet-4.6 pricing. |
ASHLR_SESSION_BUDGET_TOKENS | unset | Token budget for the session, enforced by the budget-guard PreToolUse hook. It estimates spend from ~/.ashlr/session-log.jsonl (about 4 bytes per token), adds a warning to the context at 80% and 95%, and blocks tool calls (exit 2) at 100%. With ASHLR_SESSION_LOG=0 it has no data and never blocks. /ashlr-budget sets it. |
ASHLR_SESSION_BUDGET_USD | unset | Cost budget for the session in USD, enforced by the same hook with the same 80%, 95% and 100% steps. The estimate uses a fixed blended rate, not ASHLR_PRICING_MODEL. |
ASHLR_ECO | unset | Set to 1 to turn on eco mode. The eco router hook sends question-shaped Task calls that name no subagent_type to ashlr:ashlr:explore, and the session-start hook defaults /ashlr-brief to standard when no brief level is set. See /ashlr-eco-mode. |
ASHLR_CALIBRATE | unset | Set to 1 so that a genome-routed ashlr__grep also runs a real rg --json search (5-second timeout) and records the larger of the measured and estimated raw bytes as its baseline. It adds work to each such call. It does not use ANTHROPIC_API_KEY. |
ASHLR_STATS_UPLOAD | unset | Set to 0 to stop uploading lifetime stats. When ASHLR_PRO_TOKEN is set, stats upload at most once every 5 minutes unless this is 0. |
ASHLR_STATS_SYNC | unset | Set to 1 to write stats.json on every update instead of debouncing writes. Local only; it does not contact the cloud. |
ASHLR_DISABLE_DIGEST | unset | Set to 1 to suppress the end-of-session savings digest. |
ASHLR_TUNING | on | Set to off to stop per-repo self-tuning of compression detail and the local miss counts it learns from. Local only, counts only. |
Summarization and LLM
| Variable | Default | Description |
|---|---|---|
ASHLR_LLM_PROVIDER | auto | LLM provider for summarization: auto, anthropic, cloud, onnx, local or off. auto prefers local when ASHLR_LLM_URL is set, then tries anthropic (ANTHROPIC_API_KEY), cloud, onnx and local. local uses ASHLR_LLM_URL (LM Studio or Ollama). |
ASHLR_LLM_URL | http://127.0.0.1:1234/v1 | Endpoint for the local LLM summarizer (LM Studio / Ollama). |
ASHLR_LLM_KEY | unset | Bearer key for the local LLM endpoint. The local provider sends local-llm when it is unset. Redacted from logs. |
ASHLR_LLM_MODEL | unset | Model name sent to the local LLM endpoint. The local provider and ashlr__orient default to qwen/qwen3-coder-30b@8bit. |
ANTHROPIC_API_KEY | unset | When set, enables API-measured token counting (fire-and-forget measureTokens() calls). Also used when ASHLR_LLM_PROVIDER=anthropic. |
Genome
| Variable | Default | Description |
|---|---|---|
ASHLR_GENOME_AUTO | 1 | Set to 0 to disable the auto-propose hook that runs after every Write/Edit. Genome still exists; it just won't auto-update. |
ASHLR_GENOME_RETRIEVAL | on | Set to off to disable genome-backed grep routing. ashlr__grep falls back to ripgrep. Useful when debugging or the genome is stale. |
ASHLR_EMBED_URL | unset | Embedding endpoint, for example Ollama at http://localhost:11434/api/embeddings. When it is unset, or a call fails, ashlr uses its built-in BM25-style hash embedding, which needs no model. |
ASHLR_EMBED_THRESHOLD | 0.68 | Cosine similarity threshold (0 to 1) for an embedding-cache hit. Lower = more results, higher = stricter matching. A value outside 0 to 1 falls back to 0.68. scripts/embed-tune.ts suggests a value from your own calibration log. |
ASHLR_EMBED_MODEL | nomic-embed-text | Model name sent to ASHLR_EMBED_URL. |
ASHLR_EMBED_FORMAT | ollama | Set to openai to call an OpenAI-compatible /v1/embeddings endpoint (for example LiteLLM) at ASHLR_EMBED_URL. Opt-in; https, or http only to 127.0.0.1 / [::1], no redirects. |
ASHLR_EMBED_KEY | unset | Optional Bearer key for ASHLR_EMBED_FORMAT=openai. A Phantom phm_ placeholder is sent unchanged; never logged. |
ASHLR_PREFETCH | on | Set to off (or 0, false, no) to disable background prefetch warming after ashlr__read calls (Pro and Team). |
ASHLR_GENOME_REQUIRE_OVERLAP | on | Set to 0 to turn off the auto-propose relevance gate. By default, once the genome manifest has 3 or more sections, an auto-observation is written only when it shares a word with a section title, summary or tag. |
ASHLR_GENOME_LLM_SYNTHESIS | auto | Session-end consolidation runs new proposals through an LLM when an endpoint is reachable (ASHLR_LLM_URL, ANTHROPIC_API_KEY or OPENAI_API_KEY), otherwise it uses deterministic dedup. Set to 1 to always try the LLM, or 0 to never use it. |
ASHLR_CLOUD_GENOME_DISABLE | unset | Set to 1 to turn off the team-cloud genome: no pull into the ~/.ashlr/genomes/ cache at session start and no push at session end. See docs/cloud-genome.md. |
ASHLR_OLLAMA_AUTO | unset | Set to 1 so /ashlr-ollama-setup pulls the recommended model without prompting, the same as --yes. |
Pro / Cloud
| Variable | Default | Description |
|---|---|---|
ASHLR_PRO_TOKEN | unset | Bearer token for api.ashlr.ai. Set after running /ashlr-upgrade. Enables cloud genome sync, hosted summarization, and stats upload. |
ASHLR_PRO_ASSUME | unset | Set to true (any nonempty value except 0, false, no or off) to treat this machine as Pro without reaching api.ashlr.ai, skipping the cached-tier staleness check. Meant for offline or air-gapped work. ashlr-plugin doctor reports when it is on. |
ASHLR_API_URL | https://api.ashlr.ai | Override the Pro backend URL. Use for self-hosted enterprise deployments. |
ASHLR_KEYCHAIN | on | Set to 0 to keep ASHLR_PRO_TOKEN out of the OS keychain (macOS security, Linux secret-tool) and use only the 0600 ~/.ashlr/env file. |
ASHLR_POLICY_ENFORCE | on | Set to 0 to turn off the policy hook. When ASHLR_PRO_TOKEN is set, it fetches the policy from the Pro backend before Edit, Write, Bash and MultiEdit calls and applies its deny and require-confirm rules. |
ASHLR_NO_BROWSER | unset | Set to 1 so /ashlr-upgrade prints the sign-in and checkout URLs instead of opening a browser (SSH, CI, headless). |
ASHLR_SITE_URL | https://plugin.ashlr.ai | Override the website URL that /ashlr-upgrade links to. |
Telemetry
| Variable | Default | Description |
|---|---|---|
ASHLR_TELEMETRY | unset | Set to on to opt into anonymous usage telemetry. Telemetry is off by default. What's sent: opaque session hash, tool call counts, no paths or content. See docs/telemetry.md for the full contract. |
ASHLR_TELEMETRY_URL | https://telemetry.ashlr.ai/v1/events | Override the endpoint that opted-in telemetry is flushed to. |
Pulse (self-hosted observability)
The hooks/pulse-emit.ts PostToolUse hook exits immediately unless ASHLR_PULSE_OTLP_ENDPOINT is set. It sends no prompts, completions, paths or tool inputs; the project folder is sent only as a hash.
| Variable | Default | Description |
|---|---|---|
ASHLR_PULSE_OTLP_ENDPOINT | unset | OTLP/HTTP traces URL of your own Pulse server, for example http://host/api/otlp/v1/traces. When set, the hook sends one span per tool call. |
ASHLR_PULSE_PAT | unset | Bearer token minted on the Pulse server. Production servers require it. |
ASHLR_PULSE_USER | $USER, else dev-local | Value of the x-ashlr-user header sent when ASHLR_PULSE_PAT is unset. Development servers only. |
ASHLR_PULSE_TIMEOUT_MS | 1500 | Timeout for each span POST. |
UI / status line
| Variable | Default | Description |
|---|---|---|
ASHLR_STATUS_ANIMATE | auto | The status-line gradient animates when the terminal reports truecolor (COLORTERM=truecolor or 24bit). Set to 0 to turn it off, for example in CI, or 1 to force it on. |
ASHLR_DISABLE_MILESTONES | unset | Set to any value other than 0 to stop the status line's one-time savings celebrations (first saved call, 10k lifetime tokens). |
Access control
| Variable | Default | Description |
|---|---|---|
ASHLR_ALLOW_PROJECT_PATHS | unset | Extra workspace roots the MCP server may access outside the launch cwd. Use absolute paths, separated by : on Unix or ; on Windows. |
ASHLR_LAUNCH_CWD | (set by the launchers) | The folder the host started the MCP server in. The launchers record it before moving into the plugin directory, and the router adopts it as the project root. Leave it unset; it is listed so you recognize it in a process environment. |
ASHLR_HTTP_ALLOW_PRIVATE | unset | Set to 1 to allow ashlr__http to access private/LAN hosts (e.g. localhost, 192.168.*). Blocked by default for safety. |
ASHLR_REQUIRE_GH_CONFIRM | unset | Set to 1 to require explicit confirmation before any GitHub write operation (ashlr__issue_create, ashlr__pr_approve, etc.). |
ASHLR_GATEWAY_STRICT | unset | Set to 1 (or true, yes, on) to send a model request that carries a key only to 127.0.0.1 or [::1], to a host in ASHLR_GATEWAY_HOSTS over https, or to api.anthropic.com, api.openai.com or api.ashlr.ai on 443. Redirects and credentials in the URL are refused. |
ASHLR_GATEWAY_HOSTS | unset | Comma-separated exact host:port entries allowed under ASHLR_GATEWAY_STRICT, for example a LiteLLM gateway. |
Experimental
| Variable | Default | Description |
|---|---|---|
ASHLR_PIPE_ENABLE | unset | Set to 1 to register the experimental ashlr__pipe tool. It is excluded from the default tool count. See ashlr__pipe. |
ASHLR_PIPE_ALLOW_BASH | unset | Set to 1 to allow bash() calls inside ashlr__pipe expressions. Requires ASHLR_PIPE_ENABLE=1. |
ASHLR_ORCHESTRATE_REAL_LLM | unset | Set to 1 to use a real LLM for orchestration graph expansion (instead of the stub). |
No-install
| Variable | Default | Description |
|---|---|---|
ASHLR_NO_AUTO_INSTALL | unset | Set to 1 to stop the launchers from installing Bun when it is not on PATH or in ~/.bun/bin. |
Related
- Architecture — how env vars are consumed by each component
- Settings — JSON-based settings that override some of these vars
ashlr__pipe— the experimental pipe tool- Savings math —
ASHLR_PRICING_MODELandANTHROPIC_API_KEYeffects on the ledger