ashlr

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

VariableDefaultDescription
ASHLR_HOOK_MODEredirectPreToolUse 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_DISABLEunsetSet to 1 to revert to legacy per-server mode (kill-switch, one release cycle only).
ASHLR_MCP_HOSTgeneric via CLI launchersMCP 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_MODEnudgeCodex hook behavior. nudge injects additionalContext, off disables Codex nudges, and redirect is reserved for proven redirect-compatible hooks.
ASHLR_DEBUGunsetAny 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_PREFLIGHTunsetSet 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

VariableDefaultDescription
ASHLR_TASK_PASSTHROUGHunsetSet to 1 to let native TaskList and TaskGet through instead of redirecting them to ashlr__task_list and ashlr__task_get.
ASHLR_EDIT_MIN_CHARS80Minimum combined length of old_string and new_string before the Edit hook redirects to ashlr__edit. Smaller edits pass through to native Edit.
ASHLR_ENFORCEunsetLegacy. 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_ENFORCEunsetSet to 1 to turn off the legacy ASHLR_ENFORCE=1 blocking.
ASHLR_HOOK_TIMEOUT_MS2000Safety-net timeout for each hook process. A hook that runs longer exits 0 so it never blocks the tool call.
ASHLR_HOOK_TIMINGSonSet to 0 to stop writing ~/.ashlr/hook-timings.jsonl, the data behind /ashlr-hook-timings.
ASHLR_BLOCK_WINDOW_MS10000How long after a redirected native call a matching ashlr__* call still counts as converted in the session log.
ASHLR_PERMISSIONS_CONSENTunsetSet to skip so the session-start hook never adds the ashlr tool wildcard to the Claude Code allow list.
ASHLR_QUIETunsetSet to 1 to silence the session-start greeting (welcome box, last-session savings line and weekly summary). Session state is still recorded.
ASHLR_NO_GREETunsetSet to 1 to skip the session-start greeting but keep its state updates.

Edit tools

VariableDefaultDescription
ASHLR_EDIT_FUZZYonSet 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_VALIDATEunsetSet to block to refuse an edit that introduces a syntax error. By default such an edit is still written.

Storage paths

VariableDefaultDescription
ASHLR_HOME_OVERRIDE$HOMEHome directory that contains .ashlr/ (stats.json, session-log.jsonl, caches). Intended for tests and sandboxes; normal installs leave it unset.
ASHLR_SESSION_LOGunsetSet to 0 to stop writing ~/.ashlr/session-log.jsonl and session events. It is a kill switch, not a path.
ASHLR_STATS_BACKENDjsonStats 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.dbPath to the SQLite DB when ASHLR_STATS_BACKEND=sqlite.
ASHLR_CONTEXT_DB_DISABLEunsetSet to 1 to disable the SQLite context tracking DB.

Session accounting

VariableDefaultDescription
ASHLR_SESSION_ID(from CLAUDE_SESSION_ID)Session bucket key. Inherited from the Claude Code harness. Override to isolate test sessions.
ASHLR_PRICING_MODELsonnet-4.6Model 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_TOKENSunsetToken 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_USDunsetCost 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_ECOunsetSet 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_CALIBRATEunsetSet 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_UPLOADunsetSet 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_SYNCunsetSet to 1 to write stats.json on every update instead of debouncing writes. Local only; it does not contact the cloud.
ASHLR_DISABLE_DIGESTunsetSet to 1 to suppress the end-of-session savings digest.
ASHLR_TUNINGonSet 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

VariableDefaultDescription
ASHLR_LLM_PROVIDERautoLLM 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_URLhttp://127.0.0.1:1234/v1Endpoint for the local LLM summarizer (LM Studio / Ollama).
ASHLR_LLM_KEYunsetBearer key for the local LLM endpoint. The local provider sends local-llm when it is unset. Redacted from logs.
ASHLR_LLM_MODELunsetModel name sent to the local LLM endpoint. The local provider and ashlr__orient default to qwen/qwen3-coder-30b@8bit.
ANTHROPIC_API_KEYunsetWhen set, enables API-measured token counting (fire-and-forget measureTokens() calls). Also used when ASHLR_LLM_PROVIDER=anthropic.

Genome

VariableDefaultDescription
ASHLR_GENOME_AUTO1Set 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_RETRIEVALonSet to off to disable genome-backed grep routing. ashlr__grep falls back to ripgrep. Useful when debugging or the genome is stale.
ASHLR_EMBED_URLunsetEmbedding 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_THRESHOLD0.68Cosine 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_MODELnomic-embed-textModel name sent to ASHLR_EMBED_URL.
ASHLR_EMBED_FORMATollamaSet 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_KEYunsetOptional Bearer key for ASHLR_EMBED_FORMAT=openai. A Phantom phm_ placeholder is sent unchanged; never logged.
ASHLR_PREFETCHonSet to off (or 0, false, no) to disable background prefetch warming after ashlr__read calls (Pro and Team).
ASHLR_GENOME_REQUIRE_OVERLAPonSet 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_SYNTHESISautoSession-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_DISABLEunsetSet 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_AUTOunsetSet to 1 so /ashlr-ollama-setup pulls the recommended model without prompting, the same as --yes.

Pro / Cloud

VariableDefaultDescription
ASHLR_PRO_TOKENunsetBearer token for api.ashlr.ai. Set after running /ashlr-upgrade. Enables cloud genome sync, hosted summarization, and stats upload.
ASHLR_PRO_ASSUMEunsetSet 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_URLhttps://api.ashlr.aiOverride the Pro backend URL. Use for self-hosted enterprise deployments.
ASHLR_KEYCHAINonSet 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_ENFORCEonSet 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_BROWSERunsetSet to 1 so /ashlr-upgrade prints the sign-in and checkout URLs instead of opening a browser (SSH, CI, headless).
ASHLR_SITE_URLhttps://plugin.ashlr.aiOverride the website URL that /ashlr-upgrade links to.

Telemetry

VariableDefaultDescription
ASHLR_TELEMETRYunsetSet 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_URLhttps://telemetry.ashlr.ai/v1/eventsOverride 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.

VariableDefaultDescription
ASHLR_PULSE_OTLP_ENDPOINTunsetOTLP/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_PATunsetBearer token minted on the Pulse server. Production servers require it.
ASHLR_PULSE_USER$USER, else dev-localValue of the x-ashlr-user header sent when ASHLR_PULSE_PAT is unset. Development servers only.
ASHLR_PULSE_TIMEOUT_MS1500Timeout for each span POST.

UI / status line

VariableDefaultDescription
ASHLR_STATUS_ANIMATEautoThe 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_MILESTONESunsetSet to any value other than 0 to stop the status line's one-time savings celebrations (first saved call, 10k lifetime tokens).

Access control

VariableDefaultDescription
ASHLR_ALLOW_PROJECT_PATHSunsetExtra 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_PRIVATEunsetSet to 1 to allow ashlr__http to access private/LAN hosts (e.g. localhost, 192.168.*). Blocked by default for safety.
ASHLR_REQUIRE_GH_CONFIRMunsetSet to 1 to require explicit confirmation before any GitHub write operation (ashlr__issue_create, ashlr__pr_approve, etc.).
ASHLR_GATEWAY_STRICTunsetSet 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_HOSTSunsetComma-separated exact host:port entries allowed under ASHLR_GATEWAY_STRICT, for example a LiteLLM gateway.

Experimental

VariableDefaultDescription
ASHLR_PIPE_ENABLEunsetSet to 1 to register the experimental ashlr__pipe tool. It is excluded from the default tool count. See ashlr__pipe.
ASHLR_PIPE_ALLOW_BASHunsetSet to 1 to allow bash() calls inside ashlr__pipe expressions. Requires ASHLR_PIPE_ENABLE=1.
ASHLR_ORCHESTRATE_REAL_LLMunsetSet to 1 to use a real LLM for orchestration graph expansion (instead of the stub).

No-install

VariableDefaultDescription
ASHLR_NO_AUTO_INSTALLunsetSet to 1 to stop the launchers from installing Bun when it is not on PATH or in ~/.bun/bin.
  • 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_MODEL and ANTHROPIC_API_KEY effects on the ledger

On this page