yvgude--lean-ctx/docs/reference/appendix-paths-and-config.md

Appendix — Paths, Env Vars & Config

Where lean-ctx stores everything, every environment variable that changes its behavior, and every config section. Source: rust/src/core/data_dir.rs, rust/src/core/config/.

---

1. Directories (XDG Base Directory layout)

Since GH #408 lean-ctx separates its files into the standard XDG categories so the config dir can be mounted read-only. Typed resolvers live in rust/src/core/paths.rs (config_dir(), data_dir(), state_dir(), cache_dir(), runtime_dir()).

Category	Default	Override	Contents
Config	$XDG_CONFIG_HOME/lean-ctx (~/.config/lean-ctx)	LEAN_CTX_CONFIG_DIR	config.toml, env.sh, shell-hook.* — RO-safe
Data	$XDG_DATA_HOME/lean-ctx (~/.local/share/lean-ctx)	LEAN_CTX_DATA_DIR	sessions/, vectors/, graphs/, knowledge/, archives/, memory/, packages/, agents/, stats.json, client-id.json
State	$XDG_STATE_HOME/lean-ctx (~/.local/state/lean-ctx)	LEAN_CTX_STATE_DIR	events.jsonl, journal.md, *.log, mcp-live.json, heatmap.json, pipeline_stats.json, cost_attribution.json, context_ledger.json, cooccurrence/, tee/, dashboard.token, agent_runtime_env.json (0600)
Cache	$XDG_CACHE_HOME/lean-ctx (~/.cache/lean-ctx)	LEAN_CTX_CACHE_DIR	semantic_cache/, models/, anomaly_detector.json, *_learned.json, litm_calibration.json, context_ir_v1.json, latest-version.json, .first_run_wow_done
Runtime	dirs::data_local_dir()/lean-ctx	—	daemon.pid, daemon.sock, daemon-*.log, *.lock

Unix dir permissions: 0700. The Runtime dir is the OS data-local dir (~/.local/share/lean-ctx on Linux, ~/Library/Application Support/lean-ctx on macOS); it holds only daemon IPC and is intentionally separate from the data dir.

Resolution order (per category)

Each resolver applies the same three steps:

1. Explicit override — LEAN_CTX_<CATEGORY>_DIR set & non-empty → wins.
2. Single-dir backward-compat — existing installs never split silently. If LEAN_CTX_DATA_DIR points at a non-standard path, or legacy ~/.lean-ctx holds data, or mixed $XDG_CONFIG_HOME/lean-ctx holds data (the pre-#408 layout), then all categories collapse onto that one directory — byte-for-byte the old behavior.
3. XDG split default — a fresh install uses the per-category default above.

"Holds data" = contains a data marker (stats.json, sessions/, vectors/, graphs/, knowledge/). config.toml/hooks alone do not count, so a config-only dir does not pin the other categories back onto it.

Data-only pin (GH #594). A LEAN_CTX_DATA_DIR equal to the standard data dir ($XDG_DATA_HOME/lean-ctx) is treated as a data pin only and does not collapse config/state/cache. Older versions baked exactly that value into editor MCP env blocks; honoring it as single-dir made the MCP server read config.toml from the data dir while the CLI read it from the config dir. Now both keep the XDG split, so they always read the same config.

Don't hardcode LEAN_CTX_DATA_DIR in editor MCP configs — a custom path still forces the legacy single-dir layout. Leave it unset for the clean XDG split; existing installs are auto-detected and keep working, and setup / update strip any stale pin a previous version may have written.

Migrate an existing install to the split (opt-in)

Legacy/mixed installs keep working in single-dir mode. To adopt the four-dir layout on demand:

Command	Effect
lean-ctx doctor	Reports XDG layout: N item(s) in single dir when a split is available
lean-ctx doctor --fix	Moves data/state/cache out of the config dir into their XDG homes

The migration is all-or-nothing (partial moves would re-collapse via back-compat), idempotent/resumable (existing destinations are skipped, never clobbered) and crash-safe (atomic rename, copy+remove fallback across filesystems; the source is removed only after a successful copy). An explicit LEAN_CTX_DATA_DIR is treated as a deliberate single-dir choice and is never auto-split; runtime files are left in place.

Read-only config sandbox (the #408 goal)

Once split, the config dir holds only config.toml + hooks, so it can be mounted read-only while the writable categories live elsewhere:

--ro    $XDG_CONFIG_HOME/lean-ctx     # config.toml, shell hooks
--rw    $XDG_DATA_HOME/lean-ctx       # sessions, vectors, graphs, knowledge
--rw    $XDG_STATE_HOME/lean-ctx      # events, journals, logs, ledgers
--tmpfs $XDG_CACHE_HOME/lean-ctx      # semantic cache, models (regenerable)
#       runtime (daemon.pid/sock) lives in the OS data-local dir

Project-local lean-ctx data (in the repo, not these dirs): .lean-ctx.toml (project config override), .lean-ctx-id, .lean-ctx/.

---

2. Environment variables

There are ~120 env vars; the ones you'll actually touch are below. The full list is in rust/src/core/config/. Most have a matching config.toml key — the env var always wins.

The ones you'll use

Variable	Purpose	Default
LEAN_CTX_DISABLED=1	Bypass ALL compression + disable shell hook	unset
LEAN_CTX_RAW=1	Uncompressed output for one command	unset
LEAN_CTX_DATA_DIR	Explicit data dir; a custom path also forces legacy single-dir mode (a standard-path pin is data-only, see §1)	$XDG_DATA_HOME/lean-ctx
LEAN_CTX_CONFIG_DIR	Explicit config dir (config.toml, hooks)	$XDG_CONFIG_HOME/lean-ctx
LEAN_CTX_STATE_DIR	Explicit state dir (events, logs, ledgers)	$XDG_STATE_HOME/lean-ctx
LEAN_CTX_CACHE_DIR	Explicit cache dir (semantic cache, models)	$XDG_CACHE_HOME/lean-ctx
LEAN_CTX_PROJECT_ROOT	Explicit project root	auto-detected
LEAN_CTX_TOOL_PROFILE	minimal|standard|power	config / power
LEAN_CTX_PROFILE	Active context profile	config / coder
LEAN_CTX_COMPRESSION	off|lite|standard|max	config / lite
LEAN_CTX_RESEARCH_PROSE_CAP	Proxy research prose squeeze cap in bytes	20000
LEAN_CTX_MEMORY_PROFILE	low|balanced|performance	performance
LEAN_CTX_PROXY_PORT	Proxy port	4444
LEAN_CTX_NO_UPDATE_CHECK=1	Disable update check	unset
LEAN_CTX_ALLOW_PATH	Extra PathJail roots (path list; see §5)	unset
LEAN_CTX_EXTRA_ROOTS	Multi-root workspace roots (path list; see §5)	unset

Provider tokens (for ctx_provider)

GITHUB_TOKEN / GH_TOKEN, GITLAB_TOKEN / CI_JOB_TOKEN, JIRA_URL + JIRA_EMAIL + JIRA_TOKEN, DATABASE_URL. Optional LLM enhance: OPENROUTER_API_KEY, ANTHROPIC_API_KEY.

Internal (set by lean-ctx itself — don't set these)

LEAN_CTX_MCP_SERVER, LEAN_CTX_ACTIVE, LEAN_CTX_HOOK_CHILD, LEAN_CTX_HEADLESS, LEAN_CTX_PLUGIN_DIR, etc.

---

3. Config file (config.toml)

Global at <CONFIG_DIR>/config.toml ($XDG_CONFIG_HOME/lean-ctx/config.toml, or the single dir for legacy/mixed installs — see §1); per-project override at <repo>/.lean-ctx.toml (merged, project wins). Manage with lean-ctx config (set, schema, validate, show).

Sections

Section	What it controls
(root keys)	compression, cache, shell hook, profiles, memory caps, savings footer, proxy tri-state
[tools]	profile (minimal/standard/power), explicit enabled list
[setup]	auto_inject_rules, auto_inject_skills, auto_update_mcp
[archive]	Zero-loss tool-output archive: enabled, threshold_chars (800), max_age_hours (48), max_disk_mb (500)
[search]	BM25/dense/splade weights + candidate counts
[autonomy]	Auto preload/dedup/consolidate, cognition loop
[providers]	GitHub/GitLab/Jira/Postgres + MCP bridges
[loop_detection]	Per-tool call limits to prevent agent loops
[updates]	auto_update, check_interval_hours (6), notify_only
[boundary_policy]	Cross-project search/import + universal gotchas
[secret_detection]	Secret redaction in output
[cloud]	contribute_enabled + sync timestamps
[proxy]	Upstream URLs for Anthropic/OpenAI/Gemini
[memory.*]	Knowledge/episodic/procedural/lifecycle/gotcha/embeddings caps
[llm]	Optional local LLM enhance (Ollama)

Key defaults worth knowing:

• compression_level = "lite" (root) — light compression on by default.
• savings_footer = "always" config default, but the SavingsFooter enum default is Never so no inline footer tokens are emitted unless enabled.
• memory_profile = "performance", memory_cleanup = "aggressive".
• [memory.knowledge] max_facts = 200 — the source of doctor's "facts at capacity" warning.

---

4. Files written outside the lean-ctx dirs

Category	Examples	Written by
Shell hook	~/.zshenv, ~/.bashenv, fish, PowerShell profile	setup step 1 / init --global
Agent aliases	~/.zshrc, ~/.bashrc (lean-ctx-on/off/mode/status)	setup / init --global
MCP configs	~/.cursor/mcp.json, ~/.claude.json, ~30 editors	setup step 3 / init --agent
Agent rules (opt-in)	~/.cursor/rules/lean-ctx.mdc, AGENTS.md blocks	setup step 4
Skills (opt-in)	~/.claude/skills/lean-ctx/, …	setup step 6
Proxy env (opt-in)	RC exports, ~/.claude/settings.json, Codex config.toml	proxy enable
Autostart	~/Library/LaunchAgents/com.leanctx.{proxy,daemon,autoupdate}.plist; systemd user units on Linux	setup steps 5/9
Binary	~/.local/bin/lean-ctx	installer / dev-install

Every edit to an existing file goes through config_io::write_atomic, which writes a *.lean-ctx.bak backup first. Rules injection only rewrites content between <!-- lean-ctx --> markers — your own content is preserved. lean-ctx uninstall reverses all of the above.

---

5. Filesystem boundary — path_jail, allow_paths, extra_roots (GH #392)

All tool file access (ctx_read, ctx_edit, ctx_tree, …) is jailed under the current project_root (PathJail). Three knobs widen or remove that boundary — they overlap, so here is exactly what each one does:

Knob	Effect	Use when
allow_paths = ["…"] (root key)	Adds directories to PathJail's whitelist. Tools may read/edit under them, but ctx_tree/ctx_search do not scan them.	One extra directory needs to be readable/editable (e.g. a shared skills folder).
extra_roots = ["…"] (root key)	Same whitelist effect as allow_paths plus multi-root scanning: ctx_tree, ctx_search, overview treat them as additional project roots.	Multi-repo workspaces.
path_jail = false (root key)	Disables PathJail entirely — every absolute path is allowed.	Sandboxed environments (bwrap, containers, VMs) where the OS is the boundary.
allow_ide_config_dirs = true (root key)	Adds every supported editor's config dir to the read whitelist — registry-derived (~/.cursor, VS Code, Cline/Roo, JetBrains, …). Opt-in; exposes other agents' sessions/credentials.	Letting the agent manage MCP setup across editors.

Env equivalents (path-list syntax, : on Unix / ; on Windows): LEAN_CTX_ALLOW_PATH (= allow_paths), LEAN_CTX_EXTRA_ROOTS (= extra_roots).

Notes that save debugging time:

• ~, $VAR and ${VAR} are expanded in allow_paths / extra_roots / the env vars (since v3.8.1). On older versions "$HOME/code" was matched literally and silently never applied.
• allow_paths = ["/"] technically whitelists everything; prefer the explicit path_jail = false — lean-ctx doctor flags the "/" pattern.
• Config changes are picked up on the next tool call (mtime-based reload); no MCP server restart needed. If a change appears to do nothing, run lean-ctx doctor: it reports config parse errors (a broken config.toml silently falls back to defaults) and dead allow_paths entries (unset $VAR, missing directory), plus the effective jail state.
• Compile-time off-switch: building with the no-jail cargo feature removes the jail entirely (for trusted single-user builds).
• Removed: the LEAN_CTX_NO_JAIL=1 env var (≤ 3.7.3). It was replaced by the path_jail = false config key and the no-jail compile feature; setting the old env var has no effect on current versions.
• Home-level IDE config dirs are excluded from the jail's whitelist by default. Opt in with allow_ide_config_dirs = true (or LEAN_CTX_ALLOW_IDE_DIRS=1): the allow-list is derived from the editor registry, so it covers every supported editor — including non-dotfile layouts like VS Code (~/Library/Application Support/Code/User), Cline/Roo and JetBrains — and never drifts as editors are added. ~/.lean-ctx is always allowed, and a config file that lives directly in $HOME never widens the jail to the whole home directory. lean-ctx setup asks once (informed consent) and the relaxation is audited by lean-ctx doctor. These dirs expose other agents' sessions and credentials.