yvgude--lean-ctx/docs/reference/02-daily-use.md

Journey 2 — Daily Use

You're connected. Now you (and your AI) work in the codebase every day. This journey covers the commands and MCP tools you'll touch constantly: reading files, running commands, searching, and seeing what you saved.

Source files referenced here:

• rust/src/cli/read_cmd.rs — read / diff / grep / find / ls / deps
• rust/src/shell/ — command execution + compression
• rust/src/tools/ctx_read.rs, ctx_shell.rs, ctx_search.rs — MCP equivalents
• rust/src/core/stats/format.rs — the gain dashboard
• rust/src/cli/profile_cmd.rs — tools / profile

---

0. The two ways lean-ctx helps you every day

Path	When it fires	What you do
MCP tools	Your AI reads/searches files	Nothing — your editor calls ctx_* automatically
Shell hook	A command runs in a hooked shell	Nothing — output is compressed automatically

You rarely call the CLI by hand. The CLI commands below exist so you can (for scripts, for inspection, and to understand what your AI is doing).

---

1. Reading files

lean-ctx read <file> / ctx_read

What it does: Reads a file with compression and a session cache. The first read compresses; an unchanged re-read costs ~13 tokens instead of the whole file.

lean-ctx read src/main.rs            # auto mode
lean-ctx read src/main.rs -m signatures
lean-ctx read src/main.rs --fresh    # bypass cache

The 10 read modes (mode param):

Mode	Returns	Use when
auto	lean-ctx picks the best mode	you're unsure (default)
full	whole file, cached	you'll edit it
map	imports + API surface	context-only file
signatures	function/type signatures only	you need the API
aggressive	heavy compression	very large file
entropy	entropy-ranked lines	huge file, want the dense parts
task	lines relevant to a task	task-focused read
reference	reference handle, not content	output too big to inline
diff	lines changed since last read	re-checking a file
lines:N-M	a specific range	you know where to look

Under the hood: ctx_read consults the SessionCache; a cache hit returns a file reference instead of content. The mode predictor (mode_stats.json) learns which mode works best for which file over time.

Golden output — the same file in three modes. Reading rust/src/hooks/agents/jetbrains.rs (66 lines):

mode = map — imports + API surface only:

jetbrains.rs [66L]
  deps: super::super::resolve_binary_path
  API:
    fn ⊛ install_jetbrains_hook() @L3-55
    fn print_jetbrains_manual_step(display_path:s) @L60-66

mode = signatures — the same API as a flat signature list:

jetbrains.rs [66L]
fn ⊛ install_jetbrains_hook() @L3-55
fn print_jetbrains_manual_step(display_path:s) @L60-66

mode = full returns all 66 lines verbatim. The ⊛ marks a public/exported symbol (private items carry no marker), and the trailing @Lstart-end is the symbol's exact line span — so map and signatures convey both the file's shape and where each symbol lives in ~5 lines instead of 66, letting an agent jump straight to a function instead of issuing a follow-up search. The line-range suffix is emitted only in these navigation modes; compression-first modes (aggressive, entropy, full reads) stay byte-identical. The first read in a session may also prepend an --- AUTO CONTEXT --- block with related files and graph edges.

lean-ctx diff <a> <b> / ctx_delta

Compressed diff between two files (CLI) or incremental diff since the last read of one file (ctx_delta, the MCP tool — returns only changed lines).

---

2. Running commands

lean-ctx -c "cmd" / ctx_shell

What it does: Runs a shell command and compresses noisy output (test runners, builds, package managers) while keeping the signal.

lean-ctx -c "cargo test"             # compressed
lean-ctx -c "cargo test" --raw       # full output
lean-ctx -t "cargo build"            # tracked: full output + recorded stats
lean-ctx raw "cmd"                   # skip compression (= LEAN_CTX_RAW=1; allowlist still applies)

When the shell hook is installed, your AI's terminal commands route through this automatically — you don't type lean-ctx -c yourself. The hook respects an allowlist (shell_allowlist, ~200 binaries) and skips excluded_commands. Need one more binary? lean-ctx allow <cmd> adds it (and lean-ctx allow --list shows the effective allowlist). Output that is already token-dense — JSON or TOON — is detected and passed through instead of being re-compressed.

Safety: commands run under PathJail and the shell allowlist. Secrets in output are redacted when [secret_detection] is on (default). Set shell_strict_mode = true to block $() / backticks.

---

3. Searching & navigating

Command	MCP tool	What it does
lean-ctx grep <pat> [path]	ctx_search	Regex search, compressed results
lean-ctx find <pat> [path]	—	Find files by glob/substring
lean-ctx ls [path]	ctx_tree	Compact directory map with counts
lean-ctx deps [path]	—	Project dependencies
—	ctx_semantic_search	Meaning-based search (BM25 + embeddings)

Regex vs. semantic: use ctx_search/grep when you know the string; use ctx_semantic_search when you know the concept ("where do we validate auth tokens?"). Semantic search needs an index — it builds on first use and updates in the background.

One call instead of three: when you're exploring ("where is X handled?"), ctx_compose answers in a single call — keywords + ranked files + matches + the top symbol inline — instead of a separate search → read → search loop. It's the highest-leverage everyday power tool; see Journey 7 — Context Engineering for details.

---

4. Seeing what you saved — lean-ctx gain

What it does: The token-savings dashboard. This is where savings live — by design, lean-ctx does not print "↓80% saved" footers inline (that would cost tokens). You check gain when you want the numbers.

lean-ctx gain                # summary dashboard
lean-ctx gain --live         # live-updating
lean-ctx gain --graph        # trend graph
lean-ctx gain --daily        # per-day breakdown
lean-ctx gain --wrapped      # "year in review" summary
lean-ctx gain --svg          # shareable SVG card (social/OG image)
lean-ctx gain --share        # self-hostable HTML share page (opt-in permalink)
lean-ctx gain --json         # machine-readable

For an auditable, per-event record behind these aggregates — with tokenizer transparency, bounce-netting, and a tamper-evident SHA-256 chain — use lean-ctx savings (and lean-ctx savings verify). It's local-only and on by default; see Journey 11 §2.3.

Empty state: a fresh install shows "No savings recorded yet — and that's expected," with next steps. Savings accrue as your AI uses the ctx_* tools; the first real numbers appear after a few file reads or commands.

Golden output — a populated dashboard (real numbers from a long-running install; the "Cosmic Orbit" mascot levels up as savings grow):

lean-ctx gain — token savings dashboard

  ╭──────────────────────────────────────────────────────────────╮
  │    ◆  lean-ctx   Token Savings Dashboard                     │
  ├──────────────────────────────────────────────────────────────┤
  │    388.8M        62.6%         18,707        $983.19         │
  │    tokens saved  compression   commands      USD saved       │
  ╰──────────────────────────────────────────────────────────────╯
    past 30 days:  $971.96 saved

  Cost Breakdown  @ $2.50/M input · $10.00/M output
  ──────────────────────────────────────────────────────────────
    Without lean-ctx     $1585.68   $1552.01 input + $33.67 output
    With lean-ctx         $602.50   $580.05 input + $22.45 output
    You saved             $983.19   input $971.96 + output $11.22

Related: lean-ctx token-report (token + memory report), lean-ctx ghost (hidden token waste from uncompressed commands), lean-ctx discover (missed compression opportunities in your shell history).

---

5. Choosing how much lean-ctx exposes — lean-ctx tools

What it does: Sets the tool profile — how many of the 81 MCP tools your AI sees. Fewer tools = less per-call overhead.

lean-ctx tools minimal       # 5 essential tools
lean-ctx tools standard      # 16 tools (balanced, incl. ctx_patch)
lean-ctx tools power         # all 69 (default for existing installs)
lean-ctx tools show          # current profile
lean-ctx tools list          # what each profile contains

tools vs. profile: tools controls which MCP tools are exposed. profile (Journey 5) controls context profiles — compression and read-mode behavior. They sound similar but do different things; lean-ctx tools is the canonical entry point for tool profiles.

After changing the profile, restart your AI tool so it re-reads the tool list.

---

6. Output verbosity

lean-ctx compression standard   # off | lite | standard | max

Controls how aggressively shell/tool output is compressed (terse is an alias). max is the densest; off disables it for a session. Default is lite.

---

UX notes captured during this walkthrough

• The split between tools (MCP tool count) and profile (context behavior) is the single most confused pair of commands. The help text now states the distinction; lean-ctx tools is documented as canonical.
• gain is the only place savings are shown, intentionally. New users sometimes expect inline footers; the empty-state message now sets that expectation.