How does lean-ctx handle multiple project roots & multiple tools?

[aathanwwt]

I probably didn't RTFM carefully enough, but can someone nutshell how lean-ctx does or does not handle multiple project roots, and multiple distinct tools in flight? I am working on several projects with other coders using a variety of coding agents (clauder code, windsurf, etc etc) somtimes using multiple agents on the same project. Lean-ctx asked for a project root during install, so I gave it the root of my coding directory, under which I have several git repos cloned. Not sure what the best practice is. Comments?

[yvgude]

Hi @aathanwwt, great question — this is a common setup and lean-ctx handles it well.

How Project Root Detection Works

lean-ctx automatically detects the project root per-session — you do NOT need to set a single global root. Here's how:

1. MCP mode (Cursor, Windsurf, etc.): The editor sends a cwd or roots via the MCP protocol. lean-ctx uses this to find the nearest git repo root. Each editor session gets its own project root.
2. CLI mode (Claude Code, etc.): lean-ctx reads the current working directory and walks up to find .git/, package.json, Cargo.toml, etc.
3. Daemon mode: If you run lean-ctx serve --daemon, each connected client (via HTTP/IPC) gets a separate session scoped to its project root.

Best practice: Don't set your entire coding directory as the project root. Instead, just cd into each project and lean-ctx picks up the right root automatically. The project root you set during lean-ctx setup is just a hint — it's overridden per-session by the actual working directory.

Multiple Tools / Agents in Parallel

• Different editors on different projects: Each gets its own MCP server process with isolated session state, cache, and indices. No conflicts.
• Multiple agents on the SAME project: This works but with caveats:
  • Each agent process has its own SessionCache (in-memory file cache). No shared state between processes.
  • Knowledge (ctx_knowledge) is persisted to disk per-project, so multiple agents reading/writing knowledge is eventually consistent (last-write-wins for same keys).
  • Session state (progress, findings) is per-agent-session — it won't merge across concurrent agents.
  • The BM25 and graph indices are built per-project on disk, so they're shared (with file locking).

Recommended Setup

Instead of giving a single root:

# DON'T do this:
lean-ctx setup --project-root ~/coding/

# DO this — just run lean-ctx from within each project:
cd ~/coding/project-a && lean-ctx doctor
cd ~/coding/project-b && lean-ctx doctor

Or simply let your editor handle it — lean-ctx will auto-detect per session.

Hope that clears things up! Let me know if you have follow-up questions.

[yvgude]

Update — correction to my previous answer:

I understated lean-ctx's multi-root capabilities. lean-ctx actually has full multi-root workspace support, not just single-root auto-detection. Here's the complete picture:

True Multi-Root Support

1. MCP roots/list (automatic)

When your editor (Cursor, Windsurf, etc.) opens a multi-root workspace, it sends all workspace folders via the MCP roots/list protocol. lean-ctx:

• Picks the best root (the one with project markers like .git) as the primary root
• Registers all other roots as extra_roots automatically
• Re-resolves when you add/remove workspace folders (roots/list_changed notification)

This is fully automatic — no configuration needed.

2. extra_roots in config (manual)

For tools like Claude Code that don't use MCP roots, you can configure multi-root explicitly:

# ~/.lean-ctx/config.toml
extra_roots = ["/home/user/project-b", "/home/user/shared-lib"]

Or via environment variable:

LEAN_CTX_EXTRA_ROOTS="/home/user/project-b:/home/user/shared-lib"

3. How it works in practice

Tools like ctx_tree, ctx_search, and ctx_semantic_search support a paths array parameter for explicit multi-root queries:

ctx_tree(paths=["src/", "/other-project/lib/"])
ctx_search(pattern="MyClass", paths=[".", "/shared-lib/"])

When no explicit paths are given, these tools automatically scan across all registered roots (primary + extra_roots). The PathJail security boundary is extended to include all extra roots.

Best Practice for Your Setup

Since you have multiple git repos under one coding directory:

• In Cursor/Windsurf: Open each project as a workspace folder → lean-ctx auto-detects via MCP roots
• In Claude Code: Set extra_roots in config, or just cd into each project (lean-ctx auto-detects per CWD)
• DO NOT set your entire coding directory as the root — this disables index optimizations (scan limits, graph depth)

The rest of my previous answer about process isolation and concurrent agents remains accurate.

[fmancardi]

I'm using lean-ctx with cursor on Windows.
I Open each project as a workspace folder, but I'm getting:
I'm asking this to cursor:
use the rules related to lean-ctx
confirm if you are using lean-ctx rules

But I'm getting this on cursor:
Lean-ctx MCP root misconfigured (resolves to C:/Users/myUser). Reading the spec and searching the repo with native tools for planning.

I've also tried:
in gitbash console go to the project folder, then launch cursor from terminal

Nothing changes

Any hint?

[yvgude]

need to check seems there is a bug since last version.

[yvgude]

Thanks @fmancardi — confirmed and root-caused. It's a Windows-only bug.

Cursor reports your workspace root to lean-ctx as a file:///C:/... URI. Our URI parser didn't treat the stripped /C:/... form as an absolute Windows path, so it discarded the root and fell back to the process working directory — which Cursor sets to your home dir when it launches the MCP server. That home dir then trips the "never adopt HOME as project root" guard, which is exactly the "misconfigured (resolves to C:/Users/...)" message you see. (CI didn't catch it because the Windows URI tests had been disabled rather than fixed.)

A fix is up — it parses file:///C:/... correctly and re-enables Windows test coverage. Tracked in #465.

Workaround until the next release — pin the root explicitly via the lean-ctx MCP server env in your .cursor/mcp.json:

"env": { "LEAN_CTX_PROJECT_ROOT": "C:\\Users\\<you>\\path\\to\\project" }

That env var takes priority over root auto-detection and bypasses the URI-parsing path entirely. (Alternatively: extra_roots = ["C:\\...\\project"] in ~/.lean-ctx/config.toml.)

I'll update here once the fix ships in a release.