Troubleshooting Playbook

You are: staring at something that isn't working — your AI doesn't seem to use LeanCTX, savings are zero, a new chat forgot everything, or a command behaves oddly. This is the central playbook: symptom → one-line diagnosis → fix.

The 30-second triage

Run these three, in order. Each one's footer tells you the next step.

lean-ctx status                 # is the wiring there at all?  (5-line summary)
lean-ctx doctor                 # ~27 checks across binary/daemon/proxy/caches
lean-ctx doctor integrations    # per-IDE: MCP + hook freshness + rules, per agent

status is the fast yes/no, doctor is the deep scan, and doctor integrations pinpoints which editor is mis-wired. Most problems below are identified by one of these three and fixed by lean-ctx setup --fix.

"My AI isn't using LeanCTX at all"

Diagnose: lean-ctx doctor integrations — find your agent and read its line.

What you see	Meaning	Fix
Agent not listed	LeanCTX didn't detect it	lean-ctx init --agent <name>
MCP config … missing / drift	server not wired	lean-ctx setup --fix
Hooks … drift	shell hook missing/incomplete	lean-ctx setup --fix
Hooks … stale binary	hook points at an old install path	lean-ctx setup --fix
All ✓ but still nothing	the editor wasn't restarted	fully quit & reopen the editor

The last row is the most common: editors load MCP servers and hooks at startup, so a config written after launch only takes effect on the next restart.

"gain shows zero / savings look wrong"

A brand-new install legitimately shows "No savings recorded yet — and that's expected." Savings accrue only as the ctx_* tools and shell hook are used. If you've been working but gain is still empty, your terminal commands aren't being intercepted:

lean-ctx ghost       # hidden waste from uncompressed commands
lean-ctx discover    # missed-compression opportunities in your shell history

Then re-check the hook with doctor integrations.

"A new chat doesn't remember where we were"

Session auto-restore is failing. There's a dedicated repair tool:

lean-ctx sessions doctor          # diagnose session-restore health
lean-ctx sessions doctor --fix    # repair the latest-pointer / snapshots

Common causes: the project root changed (sessions are project-scoped), or sessions/latest.json got out of sync. sessions doctor --fix rebuilds the pointer.

"Native Read/Grep are being denied"

This is harden mode, not a bug. If you (or a teammate) ran lean-ctx harden, native file tools are intentionally denied so the agent uses the compressed ctx_* tools. Turn it off with:

lean-ctx harden --undo            # native tools allowed again

See Security & Governance for what each level does.

"My shell is broken after install"

The shell hook or proxy modified your RC file. LeanCTX always keeps a *.lean-ctx.bak backup:

lean-ctx doctor --fix             # re-runs the safe, merge-based wiring
lean-ctx proxy status             # is a *_BASE_URL export pointing at the proxy?

If a base URL "defaults to the wrong provider," check the exported *_BASE_URL values in your RC and run lean-ctx proxy disable to remove them.

"Search/indexing seems stuck or huge"

lean-ctx index status             # is each index ready + recent?
lean-ctx cache prune              # drop oversized/quarantined/orphaned indexes

If index status shows a very old build time, the watcher isn't running — lean-ctx index watch (or setup --fix) restarts it. To bound index size proactively, see Performance Tuning.

"After lean-ctx update, an editor stopped working"

update refreshes every installed shell-hook agent so hooks point at the new binary. If one agent slipped through:

lean-ctx doctor integrations      # look for 'stale binary' on the affected agent
lean-ctx setup --fix              # re-point all hooks at the current binary

When all else fails — capture a report

lean-ctx report-issue             # collects a redacted diagnostic bundle

This gathers doctor output, versions, and config (secrets redacted) so a bug report is actionable. Pair it with the exact command and the editor you used.

Decision guide

Symptom	Start here
Agent ignores LeanCTX	doctor integrations
Zero / odd savings	ghost / discover
New chat has no memory	sessions doctor --fix
Read/Grep denied	harden --undo
Shell / proxy broken	doctor --fix
Search stuck / huge	index status / cache prune
Broke after update	setup --fix
Need to file a bug	report-issue

---

Next step: harden a real deployment in Security & Governance →