# Journey 1 — Setup & Onboarding > You just installed the `lean-ctx` binary. Nothing is wired up yet. This > journey covers every command that connects lean-ctx to your tools and every > function those commands call. Source files referenced here: - `rust/src/wrap/mod.rs` — one-command wrap engine - `rust/src/wrap/snapshot.rs` — pre-wrap config backup - `rust/src/wrap/verify.rs` — MCP connection probe - `rust/src/wrap/launch.rs` — agent launch/restart logic - `rust/src/wrap/unwrap.rs` — restore pre-wrap state - `rust/src/setup.rs` — the full setup engine - `rust/src/cli/dispatch/mod.rs` — command routing - `rust/src/cli/dispatch/help.rs` — quickstart / help text - `rust/src/doctor/mod.rs` — diagnostics - `rust/src/status.rs` — connection status - `rust/src/core/editor_registry/` — per-editor MCP config writers - `rust/src/rules_inject.rs` — agent rules injection --- ## 0. What "being set up" actually means For lean-ctx to help you, three things must be true: 1. **Your AI tool knows about lean-ctx** — its MCP config lists the `lean-ctx` server (so the editor launches `lean-ctx` and can call `ctx_*` tools). 2. **Your shell knows about lean-ctx** — a hook in your shell RC file lets `lean-ctx -c "git status"` etc. compress command output. 3. **A data directory exists** — `~/.lean-ctx/` holds stats, sessions, caches, and config. Every setup command below is just a different amount of hand-holding to reach that state. Three tiers: **wrap** (one command), **onboard** (all agents), **setup** (full control). --- ## 1. `lean-ctx wrap ` — the recommended first command **What it does:** Sets up lean-ctx for one specific agent with a single command. Installs shell hooks, MCP registration, agent hooks, starts the daemon, verifies the MCP connection, and shows a summary — all automatically. ```bash lean-ctx wrap cursor # or: wrap claude / wrap codex / wrap vscode ``` **Under the hood** (`wrap::run_wrap_for_agent` in `rust/src/wrap/mod.rs`): 1. **Snapshots** existing config files for later restore via `unwrap`. 2. Installs **shell hooks** (`shell_hook::install_all`). 3. Writes **MCP server registration** via `editor_registry::write_config_with_options`. 4. Installs **agent hooks** (`hooks::install_agent_hook_with_mode`). 5. Starts the **daemon** if not already running. 6. Saves the **snapshot manifest** for `unwrap`. 7. **Probes the MCP server** — spawns `lean-ctx mcp`, sends JSON-RPC `initialize` + `tools/list`, checks `ctx_read` is present. 8. Detects whether the agent is running and gives a launch/restart hint. 9. Prints a premium **summary** with tool count and next steps. **Undo:** `lean-ctx unwrap cursor` restores all modified files from the snapshot. --- ## 1b. `lean-ctx onboard` — connect all agents at once **What it does:** Connects every AI tool found on your machine using sensible defaults, with zero questions, then prints one clear "you're connected" message. ```bash lean-ctx onboard ``` **Under the hood** (`setup::run_onboard` in `rust/src/setup.rs`): 1. Calls `run_setup_with_options({ non_interactive: true, yes: true, fix: true })` — the same engine as `setup`, but it makes every decision for you. 2. Reads the resulting `SetupReport`, finds the `editors` step, and lists which tools were actually `created`/`updated`/`already` configured. 3. Prints: connected tools, the data dir path, and exactly one next step (reload shell → restart AI tool → ask it to read a file). **Files changed:** MCP config for each detected editor, shell RC hook, `~/.lean-ctx/` created. Rules/skills are **not** injected unless you previously opted in (see §2, step 4). **Why it exists:** the full `setup` wizard is 12 steps; most users want "just connect it." `onboard` is that path — time-to-value in seconds. --- ## 2. `lean-ctx setup` — the guided wizard (full control) **What it does:** An interactive, 12-step wizard. Use it when you want to decide about the proxy, telemetry, auto-updates, compression level, and tool profile. ```bash lean-ctx setup ``` **Routing** (`dispatch/mod.rs`): with no flags it calls `setup::run_setup()`. With `--non-interactive`, `--yes/-y`, `--fix`, `--json`, or `--skip-rules` it calls `run_setup_with_options(...)` instead (no prompts). ### The first-run menu (`first_run_setup_level`) Before step 1, if you've never chosen a level, it asks: | Choice | inject_rules | inject_skills | Meaning | |--------|:---:|:---:|---------| | **[1] Minimal** (default) | ✗ | ✗ | Just MCP tools, no config-file edits | | **[2] Standard** | ✓ | ✗ | MCP tools + agent rules for optimal mode selection | | **[3] Full** | ✓ | ✓ | Tools + rules + skills + shell hooks | The choice is persisted to `config.toml` (`[setup] auto_inject_rules`, `auto_inject_skills`) so it's never asked again. This is the "non-invasive by default" behavior: lean-ctx will not touch your rules files unless you say so. ### The 12 steps (`run_setup`) | Step | Name | What it does | Files touched | |------|------|--------------|---------------| | 1 | Shell Hook | `cmd_init --global` + `install_all` — installs aliases + universal hook | `~/.zshenv`, `~/.bashenv`, RC files | | 2 | Daemon | Starts/restarts the IPC daemon for fast CLI routing | UDS socket, PID file | | 3 | AI Tool Detection | Detects installed editors, writes each one's MCP config | per-editor MCP JSON/TOML/YAML | | 4 | Agent Rules | Injects `lean-ctx` rules **only if opted in** (preserves your content) | `*/rules/lean-ctx.*`, `AGENTS.md` blocks | | 5 | API Proxy (optional) | Asks y/N; if yes, installs proxy autostart + env vars | LaunchAgent/systemd, RC env exports | | 6 | Skill Files | Installs `SKILL.md` **only if opted in** | `*/skills/lean-ctx/` | | 7 | Environment Check | Ensures data dir, migrates split dirs, runs compact doctor | `~/.lean-ctx/` | | 8 | Help Improve | Asks y/N for anonymous stats sharing | `config.toml [cloud]` | | 9 | Auto-Updates | Asks y/N; installs the 6-hourly update scheduler | LaunchAgent/systemd | | 10 | Tool Profile | Choose minimal/standard/power MCP tool set | `config.toml [tools]` | | 11 | Advanced Tuning (optional) | Compression level + tool-result archive | `config.toml` | | 12 | Code Intelligence | Builds the property graph in the background (if in a project) | `~/.lean-ctx/` graph caches | It ends with an auto-approve transparency banner, a `✓ Setup complete!` summary, and **Next steps** (reload shell, restart IDE, verify with `lean-ctx gain`). ### `run_setup_with_options` — the non-interactive engine This is the function every other entry point funnels through (onboard, install, bootstrap, update rewire). It performs the same wiring without prompts and returns a structured `SetupReport` (steps, items, warnings) that can be printed as JSON with `--json`. Key options (`SetupOptions`): - `non_interactive` / `yes` — run without a TTY; `yes` is required to actually write the shell hook in non-interactive mode. - `fix` — overwrite invalid/corrupt MCP configs (merge-based repair). - `skip_rules` — never touch rules files (CLI flag wins over config). - `force_inject_rules` — always inject rules (overrides config). - `skip_proxy` / `no_auto_approve`. The decision for rules injection is: `skip_rules` → off; else `force_inject_rules` → on; else respect `config.toml`'s `should_inject_rules()`. --- ## 3. `lean-ctx install` — the natural alias **What it does:** Plain `lean-ctx install` now runs the guided `setup` (it used to error with a usage message — fixed for UX). `install --repair` (or `--fix`) runs the non-interactive, merge-based refresh. ```bash lean-ctx install # = lean-ctx setup lean-ctx install --repair # non-interactive repair (no deletes) ``` --- ## 4. `lean-ctx bootstrap` — zero-config CI/scripts **What it does:** Non-interactive setup + fix with sensible defaults. Identical to `install --repair` but named for automation. `--json` emits a machine report. Use this in Dockerfiles / CI. ```bash lean-ctx bootstrap [--json] ``` --- ## 5. `lean-ctx init` — shell aliases & single-agent config Two distinct uses: - **`lean-ctx init --global`** — installs only the shell aliases/hook (`lean-ctx-on`, `lean-ctx-off`, `lean-ctx-mode`, `lean-ctx-status`) into your shell RC. This is step 1 of `setup`, callable on its own. - **`lean-ctx init --agent `** — configures MCP + rules + skill + hook for **one** specific agent (e.g. `cursor`, `claude`, `gemini`, `pi`). Calls `setup::setup_single_agent`, the single source of truth shared with `setup`. Use this when you only use one tool, or to re-wire after an editor update. Supported agent keys are enumerated in `agent_mcp_targets` (cursor, claude, windsurf, codex, gemini, antigravity, copilot, crush, pi, qoder, cline, roo, kiro, verdent, qwen, trae, amazonq, opencode, hermes, vscode, zed, aider, continue, neovim, emacs, sublime, …). An unknown key returns `Unknown agent ''`. > Recommendation: most users should use `onboard` (all tools) or `setup` > (guided). `init --agent` is the targeted/expert path. --- ## 6. `lean-ctx doctor` — "is everything wired up?" **What it does:** Runs ~27 diagnostic checks across binary, data dir, MCP configs, shell hook, daemon, proxy, caches, memory, and capacity, then prints a summary with an action-oriented footer. ```bash lean-ctx doctor # full diagnostics lean-ctx doctor --fix # auto-repair what's fixable lean-ctx doctor --json # machine-readable lean-ctx doctor integrations # per-IDE wiring health (every detected agent) ``` **Footer** (`doctor/mod.rs`): shows `N/M checks passed`; if any need attention, it prints `N check(s) need attention. Auto-repair what's fixable: lean-ctx doctor --fix`. Otherwise `Everything looks good.` `--fix` routes to `doctor::fix::run_fix`, which re-runs the merge-based setup and repairs MCP/rules/hook drift. **Golden output — `doctor integrations`** checks **every detected agent**, not just Cursor/Claude, and reports MCP config, hook freshness, and the rules file per agent. Hooks are verified for **staleness** (a hook pointing at an old binary path fails with `stale binary … — run lean-ctx setup --fix`), and JetBrains is shown as an **MCP snippet** because it has no auto-wiring (you paste it once):
lean-ctx doctor integrations — per-IDE wiring health (excerpt) ```text Integration health: ✓ Cursor ✓ MCP config ok (~/.cursor/mcp.json) ✓ Hooks ok (~/.cursor/hooks.json) ✓ Claude Code ✓ MCP config ok (~/.claude.json) ✓ Hooks ok (~/.claude/settings.json) ✓ Instructions ~/.claude/CLAUDE.md block + skill ✓ Codex CLI ✓ Codex MCP ok (~/.codex/config.toml) ✓ Codex hooks enabled (~/.codex/config.toml) ✓ Codex hooks.json ok (~/.codex/hooks.json) ✓ VS Code ✓ VS Code MCP ok (~/Library/Application Support/Code/User/mcp.json) ✓ JetBrains IDEs ✓ MCP snippet ready — paste into Settings → Tools → AI Assistant → MCP (~/.jb-mcp.json) ✓ Rules file ~/.jb-rules/lean-ctx.md ```
A healthy run ends with no repair line; otherwise it prints `Repair: run lean-ctx setup --fix`. Add `--json` for the same data as a `schemaVersion`-stamped report. --- ## 7. `lean-ctx status` — the quick connection check **What it does:** A lighter-weight "am I connected?" report (setup report + MCP target states), JSON-capable. Use `status` for a fast yes/no; use `doctor` for deep diagnostics. ```bash lean-ctx status lean-ctx status --json ``` **Golden output — a healthy `status`** is five lines: the doctor ratio, the last setup result, and how many agents have MCP + rules wired up: ```text lean-ctx status v3.6.26 doctor: 6/6 last setup: 2026-05-30T20:06:46+00:00 success=true mcp: 28/28 configured (detected tools) rules: 17/17 up-to-date (detected tools) report saved: /Users/you/.lean-ctx/status/latest.json ``` `mcp: 28/28` and `rules: 17/17` count **detected** agents (rules count is lower because MCP-only agents receive guidance via MCP instructions — see the [installation matrix](../integrations/installation-matrix.md)). --- ## 8. What gets written where (setup recap) | Artifact | Path (example) | Written by | |----------|----------------|------------| | Data dir | `~/.lean-ctx/` | setup step 7 | | Shell hook | `~/.zshenv` / `~/.bashenv` + RC files | setup step 1 | | MCP config | `~/.cursor/mcp.json`, `~/.claude.json`, … | setup step 3 | | Agent rules (opt-in) | `~/.cursor/rules/lean-ctx.mdc`, `AGENTS.md` blocks | setup step 4 | | Skill files (opt-in) | `~/.claude/skills/lean-ctx/`, … | setup step 6 | | Proxy env (opt-in) | RC exports + LaunchAgent/systemd | setup step 5 | | Update scheduler (opt-in) | LaunchAgent/systemd | setup step 9 | Every modification of an existing file goes through `config_io::write_atomic`, which writes a `.lean-ctx.bak` backup first. Rules injection only ever rewrites the content **between** `` markers, preserving everything else. --- ## UX notes captured during this walkthrough These are the friction points found while documenting setup; fixes already shipped are marked ✓. - ✓ Plain `lean-ctx install` no longer errors — it runs setup. - ✓ `onboard` added as the zero-prompt golden path. - ✓ Data dir path corrected across all guides (`~/.lean-ctx`, not `~/.local/share/lean-ctx`). - ✓ "Premium Features" step renamed to "Advanced Tuning (optional)". - ✓ Skill-skip message no longer points to the wrong flag. - ◯ Open: the interactive wizard is still 12 steps — consider collapsing optional opt-ins (proxy, telemetry, auto-update) behind a single "Configure advanced options? [y/N]" gate so the common path is ~4 prompts. --- lean-ctx: ctx_compose bundles search+read+symbols in one call ---