Mode switching

How switch_to_mode swaps the visible tool surface in place across all ten modes, what decides the mode at boot, and how the stale-tool guard behaves.

A
Written By Atakan KayaLast updated 3 months ago

Mode switching

LEX AI runs as a single unified process that imports every mode's tool surface at boot and mounts exactly one of them, so your coding tool sees only that one. Switching flips the visible surface in place — no full restart in the normal path — and refreshes the assistant's tool list.

How to switch

Every mode exposes a universal tool:

switch_to_mode(target_mode="brief" | "forward" | "backward" | "edit" | "review"
                          | "test" | "input" | "deploy" | "mvp_generator"
                          | "mvp_completion")

Two legacy pairwise helpers survive — switch_to_backward_mode and switch_to_forward_mode — but prefer switch_to_mode. You can also change mode from the dashboard, which writes the same override; see Setup and dashboard.

What happens on a live switch

  1. The target mode is validated against the registry.
  2. The mounted surface is unmounted and the new one mounted.
  3. A one-shot override marker is written, so an accidental restart boots into the same mode.
  4. The project .env and every discoverable MCP config are synced to reality — JSON for most tools, the [mcp_servers."lex-mcp-local"] table for Codex.
  5. The payload is re-rendered for each onboarded environment and verified; a failed sync is retried up to twice.
  6. The PyCharm Copilot tool-list cache is cleared, because that host caches tools/list in a database beside its config.
  7. A burst of notifications/tools/list_changed is sent so even aggressive clients refresh.

The result reports which tools were enabled, which disabled, which unchanged, and the new tool-surface epoch. If the live swap cannot be completed, the server persists the override and exits, so your IDE restarts it directly into the target mode rather than leaving a half-switched surface behind.

Begin a new assistant request after a switch, so it reads the new mode's tools and instructions. Continuing an old request risks the assistant calling tools from the previous surface.

Which mode you get at boot

Precedence is fixed, highest first: an explicit --mode on the lex-mcp command line; the one-shot override at ~/.lex-mcp/mode-override; a --mode argument in a nearby mcp.json; then the default, forward. The override is consumed exactly once — read, then deleted — expires after an hour, and is stamped with the project root that wrote it, so a marker left by one project cannot capture another.

LEX_MCP_MODE is only a mirror of the running mode. The server rewrites it on every start and switch and never reads it as an input, so hand-editing the variable changes nothing.

The stale-tool guard

Some hosts cache tools/list too aggressively. If the assistant calls a tool that no longer belongs to the active surface, the server intercepts it and returns a structured payload rather than a raw method-not-found error:

{ "ok": false, "stale_tool_call": true, "active_mode": "forward",
  "suggested_mode": "review", "tool_surface_epoch": 7,
  "troubleshooting": { "steps_to_resolve": [
    "Refresh tools/list in the IDE.",
    "If suggested_mode is present, call switch_to_mode(target_mode='<suggested_mode>').",
    "Retry the original tool call." ] } }

The rule is fixed: refresh, switch if a suggested_mode is given, retry — never work around it. Any ok: false is a halt, so the assistant stops, runs no further tools and no git commands, shows you the troubleshooting block and waits. Switch modes when your intent genuinely changes, never to dodge an error.

See Tool surfaces and Mode chooser next.

Was this helpful?

Your feedback shapes what we write next.