Journey: Lifecycle & Troubleshooting

You’re set up and using LeanCTX. This journey is the keep-it-healthy manual: the central symptom → diagnosis → fix playbook when something misbehaves, plus the lifecycle commands — update, uninstall, process control, cache maintenance — that keep an installation clean over months of use.

0. 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.

1. The playbook — symptom → diagnosis → fix

”My AI isn’t using LeanCTX at all”

Diagnose: lean-ctx doctor integrations — find the agent you’re using 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. Run lean-ctx ghost (hidden waste from uncompressed commands) and lean-ctx discover (missed-compression opportunities in your shell history) to confirm, then re-check the hook with doctor integrations.

gain and token-report read from the same stats store; if one shows numbers and the other doesn’t, you’re looking at savings vs. memory footprint. That’s expected (see Analytics & Insights).

”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. See Memory & Knowledge for the ACTIVE SESSION block this restores.

”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:

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 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?

Every RC edit is preserved as a *.lean-ctx.bak sibling. If a base URL “defaults to the wrong provider,” check the exported *_BASE_URL values in your RC and lean-ctx proxy disable to remove them. For the no-binary emergency fallback, see §6 below.

”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 just setup --fix) restarts it. If the BM25 index is quarantined, cache prune removes it and the next read rebuilds it. To bound index size proactively, see Performance Tuning.

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

lean-ctx update automatically refreshes every installed shell-hook agent so its 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

“macOS keeps asking to access my Documents / Desktop / Downloads”

A recurring prompt for installs whose daemon, proxy and auto-updater run as LaunchAgents — and because ad-hoc binaries change signature on every build, each update re-popped it. It is fixed structurally as of v3.8.8: the three background agents run under a sandbox-exec profile that denies access to those protected folders outright, so the kernel refuses such access silently and the prompt can no longer appear. For a stable “Allow” that survives updates, run the one-time:

lean-ctx codesign-setup           # macOS: create + trust a persistent signing identity

Installing the update that contains the fix may show the prompt one last time as the old binary is replaced; after that it stays quiet.

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 / proxy status
Search stuck/huge	index status / cache prune
Broke after update	doctor integrations / setup --fix
macOS “Documents” access prompt	codesign-setup / update to 3.8.8
Need to file a bug	report-issue (§8)

2. lean-ctx update — self-update from GitHub Releases

lean-ctx update             # check + install latest
lean-ctx update --check     # only report whether an update exists
lean-ctx update 3.8.5       # pin / roll back to a specific tagged release (v-prefix optional)
lean-ctx update --insecure  # skip checksum verification (not recommended)
lean-ctx update --skip-rules # update without touching your rules files

Pin or roll back (#447). Pass a version (lean-ctx update 3.8.5) to install that exact tagged release instead of the latest — to back out a regression or A/B an older build. It uses the same SHA256-verified download and atomic swap; only the binary changes, your data, config and logs are untouched, and a downgrade reads your existing data as-is. The auto-update scheduler keeps tracking the latest release.

Under the hood:

1. Fetches releases/latest from the GitHub API; compares the tag to your currently installed version.
2. If already current: prints “Already up to date”, then still runs a setup refresh so your wiring stays correct after an editor update — unless --check.
3. If newer: downloads the platform asset (resolving your os/arch, including glibc vs musl on Linux), verifies the SHA256 checksum (refuses to install an unverifiable binary unless --insecure), then replaces the running binary safely:
   • macOS: unlink-then-rename (avoids SIGKILL from code-page revalidation), then re-codesign.
   • Windows: rename-out / rename-in, with a deferred .bat updater if the binary is locked by a running editor MCP server.
4. Re-runs setup to keep your wiring correct.

The post-update setup refresh — why your settings are safe

This is the step behind the old “update changed my settings” complaint. It:

• Re-enables the proxy only if it was already active.
• Decides whether to touch rules files: CLI --skip-rules always wins; otherwise it respects your config.toml rules opt-in. If you never opted into rules, update will not write rules files.
• Re-runs setup, which always refreshes MCP configs (so the editor reconnects to the new binary) but only touches rules when allowed.

The unchanged version of any file LeanCTX edits is always in a sibling *.lean-ctx.bak. Rules edits only ever change content between <!-- lean-ctx --> markers.

Auto-update scheduling

lean-ctx update --schedule        # enable 6-hourly auto-update
lean-ctx update --schedule 12h    # custom interval (1–168h)
lean-ctx update --schedule notify # check + notify, don't auto-install
lean-ctx update --schedule off    # disable
lean-ctx update --schedule status # show current schedule

Backed by a LaunchAgent (macOS) / systemd user timer (Linux). No mid-session restarts — updates install in the background and take effect on next launch.

3. lean-ctx uninstall — clean removal

lean-ctx uninstall                 # remove everything lean-ctx wrote
lean-ctx uninstall --keep-config   # keep MCP configs + rules (for reinstall)
lean-ctx uninstall --dry-run       # preview every change, write nothing

Under the hood — removes, in order:

1. Shell hook + proxy env exports (RC files cleaned surgically).
2. MCP configs + rules files (unless --keep-config).
3. Agent hook files, plan-mode settings, skill dirs, project agent files.
4. Proxy autostart + daemon autostart (LaunchAgent/systemd).
5. Orphaned .lean-ctx.bak / .tmp backups across all known editor dirs.
6. The data directory (~/.lean-ctx, ~/.config/lean-ctx) + project-local .lean-ctx/ and .lean-ctx-id.

Every edit backs up first; successful surgical edits then clean their backups.

The binary is not auto-deleted (it may be running). It prints the right removal command for your install method: cargo uninstall lean-ctx, brew uninstall lean-ctx, or rm <path> — then command -v lean-ctx should print nothing.

4. lean-ctx doctor [--fix] — diagnose & repair

See Setup & Onboarding §6 for the full check list. For repair specifically:

• doctor shows what’s wrong with an action-oriented footer.
• doctor --fix re-runs merge-based setup and repairs MCP/rules/hook drift.
• doctor integrations does deep per-editor checks (Cursor/Claude Code).

5. Process control — stop, restart, dev-install

lean-ctx stop          # stop ALL lean-ctx processes (daemon, proxy, orphans)
lean-ctx restart       # restart the daemon (applies config.toml changes)
lean-ctx dev-install   # build release + atomic install + restart (dev only)

Important (macOS): the proxy runs as a LaunchAgent with KeepAlive=true. A plain kill/pkill will be respawned. lean-ctx stop unloads the LaunchAgent first, then terminates everything. Always lean-ctx stop before manually replacing the binary.

6. Emergency — “my shell is broken”

If a shell alias misbehaves:

lean-ctx-off           # disable all aliases for the current session
lean-ctx uninstall     # permanent: remove all hooks

Aliases are designed to fall back to the original command if the binary is missing, so a broken/removed binary never bricks your shell. The LEAN_CTX_DISABLED=1 env var bypasses all compression and prevents the hook from loading at all.

7. Cache & storage maintenance

lean-ctx cache list          # show file-read cache entries
lean-ctx cache stats         # cache size + hit stats
lean-ctx cache invalidate <file>  # drop one file from the read cache
lean-ctx cache clear         # clear the read cache
lean-ctx cache reset [--project]  # reset all cache (or just this project)
lean-ctx cache prune         # remove oversized/quarantined/orphaned indexes (BM25 + graphs)

Use cache invalidate <file> for surgical eviction (e.g. a file changed outside the watcher); cache reset --project wipes only the current project’s cache, while cache reset wipes everything.

Golden output — lean-ctx cache stats reports the read cache size and how often re-reads were served from it (each hit is a ~13-token read instead of a full file):

CLI Cache Stats:
  Entries:   1
  Reads:     3
  Hits:      1
  Hit Rate:  33%

The doctor warns when the BM25 cache has quarantined indexes or when the archive FTS approaches its size cap — both are resolved by the commands above.

8. Platform notes (Windows / cross-platform)

LeanCTX runs on macOS, Linux, and Windows. A few behaviors are platform-specific:

Path display. All file paths in tool output are normalized to forward slashes (C:/Users/you/proj/src/main.rs), even on Windows. Forward slashes are valid path separators on Windows, and, unlike backslashes, they are never misinterpreted as escape sequences by the JSON, markdown, or terminal layers of MCP clients. This is purely a display normalization; the underlying file operations use native paths.

Data directory. On Windows the data dir resolves the same way (paths reference): %LEAN_CTX_DATA_DIR% → ~/.lean-ctx with markers → XDG → fallback. ~ is your user profile (C:\Users\<you>).

Shell hook. PowerShell uses ~/Documents/PowerShell/Microsoft.PowerShell_profile.ps1; Git Bash / MSYS2 uses the bash hook. LeanCTX auto-detects MSYS-style /c/Users/... paths and converts them to C:/Users/....

Autostart. Windows has no LaunchAgent/systemd equivalent wired up; the proxy and daemon run on demand rather than via an OS autostart unit.

9. Reporting a problem — report-issue

When something is wrong and doctor --fix didn’t resolve it, LeanCTX can open a pre-filled GitHub issue that bundles your diagnostics:

lean-ctx report-issue              # (alias: lean-ctx report)

This gathers version, platform, integration status, and recent diagnostics (secrets redacted) into an issue template so maintainers get a reproducible report. Review the contents before submitting — nothing is sent without your confirmation.

Best practice: run lean-ctx doctor --json first, attach that output, and describe the exact command and the client (Cursor/Claude/…) you were using.