Workflows

Plan Mode — IDE Compatibility

How LeanCTX integrates with Plan Mode across different IDEs. Automatic configuration for VS Code Copilot, Claude Code, Cursor, Kiro, and more.

Many AI-powered IDEs offer a Plan Mode (or Plan Agent) that researches your codebase and creates implementation plans before writing any code. LeanCTX provides read-only tools that are ideal for this research phase — cached file reads, code search, directory maps, and project overviews.

Starting with v3.6.13, lean-ctx setup automatically configures plan mode support for IDEs that require it.

IDE Compatibility Matrix

IDE	Plan Mode	MCP in Plan?	Config needed?
VS Code / Copilot	`/plan` agent	Only if configured	Yes — auto-configured by lean-ctx
Claude Code	`plan` mode	Only if allowed	Yes — auto-configured by lean-ctx
Cursor	Shift+Tab	All MCP tools	No
Kiro	`/plan` agent	All MCP tools	No
Windsurf	Plan mode	All MCP tools	No
Codex CLI	Plan mode	All MCP tools	No
Zed	No dedicated mode	Via Agent Panel	No
JetBrains	No dedicated mode	Via AI Chat	No

VS Code / GitHub Copilot

VS Code's Plan Agent (/plan) only has access to MCP tools that are explicitly listed in the github.copilot.chat.planAgent.additionalTools setting. Without this, Copilot cannot use LeanCTX during the planning phase.

Automatic Setup

Running lean-ctx setup or lean-ctx init --agent vscode automatically adds the required settings to your VS Code settings.json:

VS Code settings.json

{

"chat.mcp.enabled": true,

"github.copilot.chat.planAgent.additionalTools": [

"lean-ctx_ctx_read",

"lean-ctx_ctx_search",

"lean-ctx_ctx_tree",

"lean-ctx_ctx_overview",

"lean-ctx_ctx_plan",

...

]

}

Manual Setup

If you prefer manual configuration, add the tools to your VS Code settings.json (Cmd+Shift+P → "Open User Settings (JSON)"):

settings.json

"github.copilot.chat.planAgent.additionalTools": [

"lean-ctx_ctx_read",

"lean-ctx_ctx_search",

"lean-ctx_ctx_tree",

"lean-ctx_ctx_overview",

"lean-ctx_ctx_plan",

"lean-ctx_ctx_metrics",

"lean-ctx_ctx_compress",

"lean-ctx_ctx_session",

"lean-ctx_ctx_knowledge",

"lean-ctx_ctx_graph",

"lean-ctx_ctx_retrieve",

"lean-ctx_ctx_provider"

]

Important: Make sure you're using Agent Mode in Copilot, not regular Chat mode. MCP tools are only available in Agent Mode. Switch via the dropdown in the Copilot chat panel.

Claude Code

Claude Code blocks MCP tools in plan mode by default unless they are explicitly allowed in the permissions configuration. This is a known limitation.

Automatic Setup

lean-ctx setup or lean-ctx init --agent claude-code automatically adds lean-ctx read-only tools to ~/.claude/settings.json:

~/.claude/settings.json

{

"permissions": {

"allow": [

"mcp__lean-ctx__ctx_read",

"mcp__lean-ctx__ctx_search",

"mcp__lean-ctx__ctx_tree",

...

]

}

Cursor

Cursor's Plan Mode (activated via Shift+Tab) automatically has access to all MCP tools in read-only mode. No additional configuration is needed — LeanCTX works out of the box.

Other IDEs

Kiro (AWS)

Kiro's Plan Agent (/plan or Shift+Tab) automatically accesses MCP tools during the research phase. No configuration needed.

Windsurf

Windsurf's Plan mode provides identical MCP tool access as Code mode. No configuration needed.

Codex CLI

Codex CLI's plan mode uses all configured MCP tools from config.toml. No configuration needed.

Recommended Tools for Plan Mode

The following tools are safe for plan and research phases — they gather context without editing your source code:

Tool	Description
`ctx_read`	Read files with 10 compression modes (cached)
`ctx_search`	Token-efficient code search across the project
`ctx_tree`	Compact directory maps with filtering
`ctx_overview`	Project overview with dependency graph
`ctx_plan`	Context-aware planning with budget estimation
`ctx_metrics`	Token savings and performance metrics
`ctx_compress`	Compress context when budget is tight
`ctx_session`	Session management and state tracking
`ctx_knowledge`	Knowledge graph: recall decisions and insights
`ctx_graph`	File dependency graph analysis
`ctx_retrieve`	Retrieve specific cached context
`ctx_provider`	Query external data sources (GitHub, Jira, etc.)

Troubleshooting

lean-ctx tools not appearing in plan mode

Run lean-ctx doctor — check the "Plan mode" line for your IDE
Run lean-ctx setup to auto-configure plan mode settings
Restart your IDE after configuration changes

VS Code: "0 tool calls" in plan mode

Verify you're in Agent Mode (not Chat mode)
Check that chat.mcp.enabled is true in VS Code settings
Verify planAgent.additionalTools contains lean-ctx tools
Run lean-ctx status to confirm the MCP server is running

Client detected as "unknown (tier 4)"

If VS Code sends "Visual Studio Code" as the client name and LeanCTX shows unknown (tier 4), add LEAN_CTX_CLIENT_HINT to your MCP config as a workaround:

.vscode/mcp.json

"env": {

"LEAN_CTX_DATA_DIR": "/path/to/.lean-ctx",

"LEAN_CTX_CLIENT_HINT": "vscode-copilot"

}

This is fixed in v3.6.13+ where "Visual Studio Code" is automatically recognized.