Brief
An interview that turns a rough idea into .lex/contract.md, then hands off to the build mode that fits. Start here when the scope is not yet settled.
LEX AI documentation hub
LEX AI is a local FastMCP server that lets an AI coding assistant specify, create, document, edit, review, test, re-target, deploy, and complete LEX App projects through purpose-built workflow modes.
Current system
One unified server, ten tool surfaces, one active mode at a time.
The recommended entry point is lex-mcp. It imports all ten mode servers and exposes exactly one mode's tools to the assistant. Mode switching is live in the unified runner and refreshes the client tool list.
Forward
New LEX App product creation through a 20-step planning, implementation, hardening, wiki, and sync flow.
Backward, edit, review
Document a codebase, make a focused change, or run an audit without using the full forward workflow.
Test, input, deploy
Write a suite and prove it catches regressions, adapt the app to a changed input-data format, or get it running in a target environment.
MVP generator and completion
Create a capped MVP quickly, then expand it to full-product scope with completion mode.
Shared capabilities
All ten surfaces can read your spreadsheets and PDFs directly and put a question to you through your tool's own dialog.
One mode is visible at a time
Exposing ten tool surfaces at once would leave the assistant choosing between forty-plus tools on every turn. Instead the server mounts exactly one mode and swaps it live on switch_to_mode, so the tools on offer are always the ones the current job needs.
Set up LEX AI and open the dashboard
Start from the LEX project folder you want the assistant to work on.
Prepare the workspace
This wires the local MCP package into the project and IDE configuration.
lex setup-with-aiPass --environment to pick your coding tools explicitly, or --list-environments to see every supported one.
Open the control surface
Confirm active project, credentials, configuration, and mode before asking the IDE assistant to work.
lex ai-dashboardCheck active project
The server resolves project roots from explicit paths, project env, cwd markers, and virtualenv location. The dashboard is where users confirm the result.
Choose active MCP mode
The dashboard updates the passive mode state and asks the running server to expose the requested tool surface.
Start a fresh assistant request
After mode changes, give the IDE assistant a new request so it uses the current tools and instructions.
Use the dashboard as the control surface
The dashboard is the normal place to inspect configuration and select the active workflow mode before starting an IDE assistant request.
Confirm project context
Check that the resolved project path is the LEX project you expect. If not, run from the right folder or set LEX_MCP_PROJECT_DIR.
Choose the workflow mode
Pick the mode that matches user intent. The unified server then exposes that mode's tool surface.
Verify server health
Use the dashboard together with the IDE MCP server panel to confirm that lex-mcp-local is running and has refreshed tools.
lex ai-dashboardSupported coding tools
LEX AI officially supports seven agentic coding environments. The number is exact rather than aspirational: a test asserts that all seven render all ten workflow modes.
JetBrains, VS Code, CLI
The JetBrains entry covers the whole IntelliJ family. All three receive the agent payload in the documented GitHub layout, byte for byte.
Rules and commands
Payload lands as an always-on .cursor/rules/ workspace rule, slash commands in .cursor/commands/, and step agents in a neutral .lex/agents/ tree.
Native subagents
Maps one-to-one onto native features: subagents in .claude/agents/, slash commands in .claude/commands/, and workspace memory merged into CLAUDE.md. Covers the CLI and the Claude Desktop Code tab.
TOML config
The only environment whose MCP config is TOML. It is written by a line-level splice, so every unrelated comment and formatting choice in your config survives.
Workflows and rules
Rules in .windsurf/rules/with Windsurf's own trigger keys, and slash commands as .windsurf/workflows/.
Translated, not dumped
Each mode ships one canonical payload tree. Copilot surfaces get it verbatim; the rest get a genuine translation into their own conventions. Editing the canonical tree updates all seven at once.
What "supported" guarantees
Registration in that tool's own config format and location; the full agent payload in its native layout; mode switching that rewrites both; self-repair on every tool call, restoring assets that were deleted or edited; and a documented next step for that specific tool. Where a host has no named subagents (Cursor, Codex, Windsurf) the step agents ship to a neutral tree and the workspace rules gain an explicit delegation protocol, so the coordinator loop and per-step isolation survive intact.
Merge-preserving writes
Unrelated MCP servers, unknown settings and TOML comments all survive. CLAUDE.md and AGENTS.md are only rewritten between managed-block markers — text outside is preserved byte for byte.
A manifest of what was written
.lex/ai-assets.json records every generated file per environment, so deselecting a tool removes exactly what LEX AI created and nothing else. Because the MCP configs hold live credentials, setup also writes a managed .gitignore block and warns, by path, about anything git already tracks.
lex setup-with-ai --list-environmentsChoose the right workflow path
Use user intent first. Tool names are secondary.
Clarification rule
Ask exactly one clarification question when user intent matches multiple rows. Never switch modes merely to bypass an error.
Canonical modes
The ten canonical mode names are brief, forward, backward, edit, review, test, input, deploy, mvp_generator, and mvp_completion.
Project intake
A guided interview over 7 topics and 20 contract fields that writes .lex/contract.md, then names the build mode to hand off to.
Full new project
20-step workflow: planning, implementation, hardening, technical-map wiki, and sync.
Reverse documentation
18 steps: scan existing code, generate wiki material, ask discovery questions, and create canonical docs.
Targeted edits
A 22-task catalog with auto-injected sustainability tasks.
On-demand audits
Flat review flow for convention and business compliance reports. Changes nothing.
Prove the test suite
10 responsibilities that ground tests in user stories, then prove each one would actually fail if the behavior broke.
Changed input format
7 change areas that migrate an app to renamed columns, a new delimiter or encoding, or a new row grain.
Run it somewhere
Sequential deployment steps served by the Lex handbook, with an independent verifier proving the app actually runs.
Capped MVP
Six-checkpoint MVP generator with hard scope caps and boot-checklist gate.
MVP to full product
Forward-style completion flow that starts at step 9 and expands a prior MVP.
Not sure which one?
Start with brief. The interview ends by naming the mode that fits what you described, so choosing correctly is the interview's job rather than yours.
Brief mode
Use Brief when you know what you want but have not written it down. The assistant interviews you one question at a time and writes the project contract the build modes work from.
Why an interview
A form with twenty expert boxes does not get filled in.
The twenty questions that make up a LEX project contract are the right questions, but asking someone to author a specification unaided does not work. So the assistant asks instead, drafts what it can, and asks you to correct it rather than write it.
Pick a scenario and start
kickstart_brief seeds the contract with what LEX already knows and returns the interview plan. The scenario decides how much rigor the interview demands and which build mode it will hand off to, so a read-only audit is never interrogated about data retention.
Answer one question at a time
get_next_question then submit_answer, repeated. Exactly one question is outstanding and the server enforces it — one question per turn cannot be a rule the assistant merely remembers.
Finalize and hand off
finalize_briefreturns the contract path, its checksum, the open decisions, and the target mode with its first tool. It refuses while an answer only you can give is still the assistant's guess.
Filler is refused at the door
"Standard", "best practice", "you decide", "tbd" — 41 filler phrases in all — are rejected against a fixed list. The refusal names the field and supplies a sharper follow-up drawn from that field's own escalation ladder, so a rejection produces a better question rather than the same one again.
Every answer records who decided it
[USER-REQUIRED] means only you could answer it. [LLM-FILLED] means the assistant drafted it and you agreed. [AUTO-FILLED] means a LEX default nobody has checked yet. Where your tool can show a dialog, the server asks you directly and the answer never passes through the model at all.
You end the interview, not the assistant
Every question carries a remaining count and a way out. finish_interview_nowstops immediately and records each unanswered field as a named gap with your own reason. "I don't know yet" is a first-class answer and becomes an open decision rather than a guess.
The contract is yours to change
.lex/contract.md is plain markdown, stays tracked in git, and can be reworded or reflowed without breaking parsing. Edits made between sessions are adopted as your own words on resume — and still validated, so the file cannot smuggle in an answer no other channel would accept.
What the build modes do with it
Forward mode picks up .lex/contract.md automatically, hashes it, and points every one of its twenty step agents at it with one instruction: you agreed to these statements, so they are requirements, not assumptions. In the generated .lex/prompt.md, anything you did not answer is marked explicitly unspecified — silence in a contract never reads as permission.
Forward mode
Use Forward for a brand-new LEX App project or a full workflow run.
Kickstart
kickstart_workflow creates a GitHub repo, initializes git, pushes the default branch, creates a run-NN workflow branch, writes the manifest, and opens the tracking issue. Use kickstart_run for an existing GitHub project.
Steps 0-19
The coordinator calls get_plan_step, delegates to lex-step-NN, then calls notify_step_complete. The coordinator does not do step work itself.
Finalize
finalize_workflow() returns audit-report instructions. finalize_workflow(audit_complete=True) commits final changes, pushes, creates a PR, attempts squash-merge, checks out default, and closes the issue.
Planning
Overview, IO, requirements, story, architecture, functions, diagrams, pseudocode, and compliance.
Implementation
Implementation plan, blueprint, and full code delivery. Existing-project runs can use lex-step-11-refactor.
Hardening
Initial data, Streamlit/dashboard work, and LEX compliance pass.
Wiki and sync
Technical-map wiki enrichment plus forward/backward doc and code reconciliation.
Backward mode
Use Backward to reverse-document an existing project.
Kickstart, scan, wiki
reverse_kickstart accepts a local path or GitHub URL. scan_project performs static AST scanning and generate_wiki writes technical-map/ and module context files.
LLM wiki review
Steps 3-6 use get_reverse_step and notify_reverse_complete with reverse step agents.
Discovery pause
generate_questionnaire writes discovery-questionnaire.md. The run pauses while the user fills required answers, then resumes with submit_questionnaire.
Canonical docs and gap report
Steps 8-16 create business docs. Step 17 produces a gap report after finalize_reverse.
Git behavior
Backward mode may clone a repository for convenience, but it does not commit, push, create branches, open PRs, or merge.
Edit mode
Use Edit for focused changes to an existing LEX app.
Kickstart and catalog
kickstart_edit starts the session. list_edit_tasks and propose_edit_plan help choose the minimum set of atomic code-change tasks.
Plan and auto-injection
set_edit_plan commits the plan. The server auto-injects sustainability tasks such as compliance, dependent-code scan, tests, docs sync, technical-map sync, and migration check when applicable.
Execute and finalize
For each task, call get_task_brief, run the named agent, then notify_task_complete, which commits that task on its own. finalize_edit writes EDIT-REPORT.md, pushes, and opens a pull request.
Required checks
lex-compliance-check is non-waivable. migration-check is non-waivable when a model-shaped change requires it.
Several runs on one repository
Each run gets its own branch and its own checkout, so a second edit — or a test run alongside one — does not compete for the working tree. Run lex ai-worktree to prepare the folder yourself, or start a second chat and LEX AI prepares it for you.
Git behavior
Edit mode version-controls its own work. It checkpoints whatever you had uncommitted on your branch, cuts a branch for the run, and commits each task separately as [edit/<task_id>] <summary> — so the code change, the dependent-code fixes, the tests and the docs land as separate commits. finalize_editpushes and opens a pull request against the base branch. It does not merge: with several runs open on one base, merging would land one run's work underneath another still building on it.
Review mode
Use Review for static audits, not implementation changes.
Framework compliance
Checks LEX App conventions, folder/model rules, FileField presence, imports, logging patterns, and cross-doc reconciliation when both doc sets exist.
Business alignment
Compares implemented code against captured business requirements and any review addenda supplied by the user.
Flow
After kickstart_review, every other tool is optional. Run one or more review types, call notify_review_complete, then finalize_review. Reports land under reviews/.
Test mode
Use Test to write the suite for an existing LEX app and then prove the suite actually catches regressions.
Why a passing test proves nothing
A test can pass because the assertion cannot fail. Test mode ends by breaking each covered behavior on purpose, confirming the test notices, then reverting exactly. Coverage in the final report counts only scenarios graded effective — a criterion whose only scenario is weak or unverified is reported as uncovered.
User stories or no session
Without a user-story document the session does not open. Expected values taken from the implementation pin current behavior, bugs included, and can never fail. dispatch_reverse_prerequisite hands the project to Backward mode to produce the stories and records the pending return, so the test session resumes on the way back.
No clean report while work is open
finalize_test_run refuses while a mandatory responsibility, the scenario matrix, real execution results, a blocking question, or an unproven acceptance criterion is outstanding. An honest early stop is always available and stamps the report INCOMPLETE with the blockers listed.
Flat, not a step march
Five are mandatory and cannot be waived: story-assurance, scenario-matrix, execution, effectiveness-audit, and gap-report. The coordinator chooses the rest.
Citations are enforced mechanically
A scenario row citing no acceptance criterion is rejected. A scenario asserting a number must cite a ground-truth source or a question actually put to you — reading a figure off a run is refused outright.
Lex tests are unusual
The JSON action chain replayed into a real database by ProcessAdminTestCase is the test, not the test data; Python assertions are an optional layer on top. Reports land in test-runs/ rather than a lowercase tests/, because on macOS and Windows that is the same directory as the Lex convention Tests/ and report output would merge into the fixture tree.
Input mode
Use Input when the data your app ingests has changed shape: renamed, added or dropped columns, a new delimiter or encoding, or a different row grain.
This is a code migration, not a setting
Lex ships no input parser. Upload files are plain Django FileFields parsed by hand-written pandas code inside calculate() methods, with column names as string literals. A renamed column is a code change in every place that literal appears.
Hand over a file, or describe it
register_format_change reads a sample server-side: CSV and TSV are sniffed for delimiter, columns and sample rows; XLSX, XLS and PDF are converted to markdown. Or describe the change verbally and the analyst agent interviews you until renames-versus-drops, types, keys and grain are unambiguous.
Only what the change touches
upload-parser, data-model, migrations, calc-fanout, reports, serializers, and test-data. There is no fixed order — the format spec decides which areas run. Skipping upload-parser, migrations or test-data raises a warning at finalize.
The failures this mode exists to prevent
All three are silent — nothing throws. A .get() default on a renamed column imports wrong data under a SUCCESS status. An orphaned validate_<field> method after a rename means validation quietly stops running. Stale binary fixtures keep the suite green against the old format. A renamed upsert key is its own hazard: it turns updates into duplicating inserts.
Deploy mode
Use Deploy to get an existing LEX app running in a target environment. It configures and runs; it does not write application code.
Kickstart and scan
kickstart_deployment takes a project path or a GitHub URL plus a target — local, staging, production, or whatever name you use. A shallow scan reports what the project already says about how it deploys: compose files, Dockerfiles, env templates, Procfile, service units, CI and infra directories.
Run the handbook steps
get_deployment_step and notify_deployment_step_complete, in sequence. Step bodies come from the Lex deployment handbook on the remote backend; the mode owns the session, the evidence record, and the report. A step body is never invented locally.
Prove it, then finalize
An independent verifier agent establishes that the application actually runs — not that the steps were performed — and never repairs what it verifies. finalize_deployment returns every step still blocked or partial, so a deployment is never presented as finished when the report says otherwise.
No secret value is ever written down
Not in a step summary, a note, the index, the report, or a log line. Only the key name and where it belongs are recorded. The report carries an explicit Secrets section saying so, and a secret found already committed is a halt rather than a finding.
Nothing is committed for you
A deployment run writes configuration, and an auto-commit is how a populated .env reaches a remote. The .env.example is the artifact; the real values stay with you.
Blocked steps are first-class
Only a step marked completed advances the cursor, so the coordinator is walked back to the blocker rather than past it. Re-running a step replaces its record instead of appending, so the report shows the last attempt rather than a history of attempts.
MVP generator and completion
Use MVP generator to start small. Use MVP completion to expand an approved MVP into full-product scope.
Six-checkpoint MVP
Kickstart, then six checkpoints: plan, scope, scaffold, implement stubs, run boot checklist, finalize. Hard caps: 10 requirements, 5 entities, and 8 fields per entity.
Completion from step 9
Assumes planning steps 0-8 exist from a prior MVP run. Runs forward-style steps 9-19 and uses the same GitHub delivery mechanics as forward mode.
Gate
finalize_mvp refuses to close while critical boot-checklist failures remain. The verifier and implementer loop until the checklist is non-blocking.
Coordinator-agent execution model
This mirrors the current docs/mcp-execution-model.md: ten modes, one active tool surface, and mode-specific orchestration rules.
Question-ordered
Not a step loop and not a catalog. The server owns which single question is outstanding.
Coordinator loop
Full new Lex App workflow over steps 0-19.
Coordinator loop
18 steps: static scan, wiki, questionnaire, canonical docs, and gap report.
Flat task catalog
Atomic change tasks plus auto-injected sustainability checks.
Flat audit run
Optional convention and business review reports.
Flat, gated at both ends
10 responsibilities behind a user-story entry gate and an effectiveness exit gate.
Flat change areas
7 areas run in whatever combination the format spec implies. No fixed order.
Sequential, remote-served
Step bodies come from the Lex handbook on the backend; the mode owns the session and the evidence.
Checkpoint gated
Plan, capped scope, deterministic scaffold, boot checklist, and report.
Coordinator loop
Forward-style completion from step 9 through 19.
Route by user intent
An unclear scope means brief. New app means forward. Initial MVP means mvp_generator. MVP completion means mvp_completion. Existing app changes mean edit. Audits mean review. Reverse documentation means backward. Test work means test. A changed input format means input. Getting it running means deploy.
Kickstart first
The first mode-specific action is the mode's kickstart tool: kickstart_brief, kickstart_workflow, kickstart_run, reverse_kickstart, kickstart_edit, kickstart_review, kickstart_test_run, kickstart_input_change, kickstart_deployment, or kickstart_mvp.
Coordinator routes, agents work
The IDE assistant calls MCP tools, receives the next brief and agent name, delegates focused work to that agent, then reports completion back to the MCP.
Server enforces order and gates
The MCP owns workflow ordering, manifests, completion checks, stale-tool recovery, git checkpoints where applicable, and structured error payloads.
Forward execution
kickstart_workflow creates a new GitHub repo and run branch. kickstart_run starts a new run branch on an existing repo. Steps 0-19 use get_plan_step, the named lex-step-NN agent, and notify_step_complete. Finalization is two-stage: first audit instructions, then finalize_workflow(audit_complete=True) for PR, squash merge, checkout, and issue closure.
Planning
Overview, IO, requirements, story, architecture, functions, diagrams, pseudocode, and compliance.
Implementation
Implementation plan, blueprint, code delivery, or step 11 refactor for existing-code reconciliation.
Hardening
Initial data, Streamlit/dashboard work, and Lex compliance pass.
Wiki and sync
Technical-map enrichment plus forward/backward doc and code reconciliation.
Forward:
kickstart_workflow(...) or kickstart_run(...)
for step in 0..19:
get_plan_step(step)
runSubagent("lex-step-NN", brief)
notify_step_complete(step, process, summary)
finalize_workflow()
write audit-report.md
finalize_workflow(audit_complete=True)Reverse docs pipeline
reverse_kickstart, scan_project, generate_wiki, steps 3-6, generate_questionnaire, user answer pause, submit_questionnaire, steps 8-16, finalize_reverse, then step 17 gap report.
Task-catalog execution
kickstart_edit, optional catalog/proposal, set_edit_plan, then per task get_task_brief, named edit agent, notify_task_complete, and finalize_edit.
Optional review types
kickstart_review, optional list_review_types, then one or more get_review_brief and notify_review_complete calls before idempotent finalize_review.
Six checkpoints
kickstart_mvp, optional checkpoint list, submit_mvp_plan, submit_mvp_scope, scaffold_mvp, record_implementation, run_boot_checklist, and gated finalize_mvp.
MVP caps
Current code allows up to 10 requirements at 240 characters each, 5 entities, and 8 fields per entity. The demo walkthrough needs at least 3 steps. Calculations should stay dumb-but-real; current code does not enforce a numeric calculation cap.
Provider swap
switch_to_mode swaps the mounted FastMCP provider, updates external state, bumps the tool-surface epoch, and sends tools/list_changed.
Structured recovery
Cached calls from an old mode return stale_tool_call: true, active mode, optional suggested mode, epoch, and refresh/retry guidance.
Downstream outputs
Runs produce manifests, planning docs, business docs, technical maps, reviews, edits, MVP reports, copied docs, and project agent rules in the downstream repo.
Stop and retry same tool
On ok: false, stop all workflow activity, show troubleshooting, wait for the user to resolve it, then retry the same MCP tool.
Tool surfaces by mode
Only one mode's tool surface is visible to your coding tool at a time. Surfaces range from 10 tools (deploy, the smallest) to 17 (test, the largest).
Four tools are on every surface
ask_user_question and record_user_answer put a question to you and record who actually authored the answer. read_input_file and render_pdf_pages read your spreadsheets and PDFs server-side. Every mode also carries switch_to_mode.
Interview tools
kickstart_brief, get_next_question, submit_answer, skip_topic, finish_interview_now, the optional interview form, status, and finalize_brief.
Workflow tools
kickstart_workflow, kickstart_run, resume_workflow, get_plan_step, notify_step_complete, finalize_workflow, status, repo inspection, and mode switching.
Reverse docs tools
reverse_kickstart, scan_project, generate_wiki, generate_questionnaire, submit_questionnaire, reverse step tools, finalize, status, and switching.
Task catalog tools
kickstart_edit, task listing, plan proposal, plan setting, task brief, completion, waiver, status, finalize, and switching.
Review tools
kickstart_review, review type listing, review brief, review completion, status, finalize, and switching.
Responsibility tools
kickstart_test_run, dispatch_reverse_prerequisite, responsibility listing, plan proposal and commit, record_scenario_matrix, record_test_execution, completion, waiver, status, and finalize_test_run.
Format-change tools
kickstart_input_change, register_format_change, get_intake_brief, area listing, change brief, completion, status, and finalize_input_change.
Deployment tools
kickstart_deployment, get_deployment_step, notify_deployment_step_complete, status, and finalize_deployment. The smallest surface of any mode.
MVP checkpoint tools
kickstart_mvp, checkpoint list, scope submission, scaffold, implementation record, boot checklist, status, finalize, and switching.
Forward-style tools
Name-identical to forward mode, but starts at step 9 and reconciles an existing MVP against full-product scope.
Reading your files, asking you things
Four tools are registered on every one of the ten mode surfaces. They are the reason a mode can work from your real data and can stop to ask rather than assume.
Spreadsheets and PDFs, read server-side
CSV, TSV, TXT, XLSX, XLSM, XLS and PDF, format autodetected, returned as markdown. Excel sheets become one table per sheet; PDF pages become text under a per-page heading. Every read returns the file's checksum, so a run can record evidence of the exact file it read.
It works where a terminal does not
Without it the assistant writes a throwaway pandas script and reads your schema out of the terminal — which fails outright on Copilot in JetBrains and sandboxed Codex, and floods the transcript everywhere else.
Scans and charts
Rasterises PDF pages as images so a multimodal model can read a scan, a chart or a stamp that has no extractable text. It reports which pages have no text layer, and flags anything read off pixels as a transcription rather than data.
Windowed, capped, checked
One call returns at most 40,000 characters with an offset for the next, so a 300-page PDF is read across several cheap calls. Files up to 200 MB are accepted. Magic bytes are checked, so a mislabelled file is refused rather than mis-parsed and reported as empty.
Asking you a question is a tool call
ask_user_questionputs one question to you through a three-rung ladder that degrades silently: your tool's own dialog first, then a local browser form, then plain text relayed by the assistant. An answer your host collected is recorded as yours; an answer the assistant relays is recorded as relayed. The two are never collapsed. A question you decline cannot be silently defaulted — the run records a disclosed gap with an explicit assumption instead of a hidden default.
Shipped agents, prompts, and instructions
One canonical payload tree per mode is the source of truth. LEX AI translates it into each supported coding tool's native format on install.
Eleven user-facing entries
/lex-brief, /lex-app, /lex-resume, /lex-reverse, /lex-reverse-resume, /lex-edit, /lex-review, /lex-test, /lex-input, /lex-deploy, and /lex-mvp. Completion mode ships no prompt of its own and is entered by switching modes.
20 step agents
lex-step-00 through lex-step-19, plus lex-step-11-refactor, docs reader, validator, and git repair support.
18 reverse agents
lex-reverse-step-00 through lex-reverse-step-17, covering scan bookkeeping, wiki review, questionnaire, canonical docs, and gap report.
Named role agents
Edit implementers and sustainability agents, review convention/business agents, ten test responsibility agents, seven input change-area agents plus an analyst, a deploy step agent and an independent verifier, and MVP scoper/implementer/verifier agents.
Not every tool has subagents
GitHub Copilot and Claude Code spawn named subagents natively. Cursor, Codex and Windsurf do not, so their step agents ship as instruction files under .lex/agents/ and the workspace rules gain an explicit delegation protocol: read the agent file in full, execute it as one focused sub-task, drop the working detail, report the summary. Only the spawning mechanism differs — the coordinator loop, the no-skip rule and the halt-on-error rule are identical.
Mode switching and stale-tool recovery
The unified runner mounts all mode servers and exposes one at a time.
Boot resolution
The server chooses the mode from CLI --mode, a one-shot override file, nearby mcp.json, then default forward. LEX_MCP_MODE is passive reflection, not an input.
Live switch
switch_to_mode validates the target, unmounts the active surface, mounts the new one, updates external state, bumps the tool-surface epoch, and emits tools/list_changed notifications.
Stale tool guard
If an IDE calls a tool from a previous mode, middleware returns a structured stale-tool payload with the active mode, optional suggested mode, and refresh/retry guidance.
Outputs created in downstream projects
These artifacts are produced in the project that consumes LEX AI, not inside this repository.
The project contract
contract.mdholds the interview's answers, tagged with who decided each one, and stays tracked in git because it is your requirements record. prompt.md is the standalone contract prompt. ai-assets.json records every file setup wrote.
Workflow manifest
Forward/completion state, active project, run branch, completed steps, file ownership, and resume context. Every other mode keeps its own dot-directory manifest so a run survives a mode switch and resumes.
Planning and business docs
plans/technical_docs/ for forward planning and audit reports; plans/business_docs/ for backward outputs and questionnaire-driven docs.
Local wiki
AST-based module/model pages plus per-module CONTEXT.mdfiles for handoff and future AI sessions. Forward mode writes this scaffold non-destructively and skips any file that already exists. Backward mode's generate_wiki rebuilds it from the current scan, so re-running that replaces what is there.
Consistent report shape
edits/<run>/EDIT-REPORT.md, reviews/REVIEW-REPORT.md, test-runs/TEST-REPORT.md, input-changes/INPUT-CHANGE-REPORT.md, deployment/DEPLOYMENT-REPORT.md, and mvp/<run>/MVP-REPORT.md — the first five beside an auto-maintained _index.md. Edit and MVP scope their output per run; the rest write straight into the folder.
Scenario data and test modules
Test mode writes JSON scenario chains and ProcessAdminTestCase modules under Tests/, plus a lex_test_config.yaml at the project root. It writes them but does not commit them — that stays with you.
What is gitignored and what is not
The generated MCP configs are gitignored because they carry your GitHub token and remote access key. CLAUDE.md, AGENTS.md and .lex/contract.md stay tracked, because they hold your own content rather than generated payload. Setup cannot untrack what git already has, so it reports anything already committed and tells you to rotate any credential in a listed config.
LEX App package AI commands
These are the user-facing lex ai-* commands whose current implementations live under src/lex_mcp/. The LEX App CLI owns the command entry points and delegates this behavior to lex-mcp-local.
lex ai-dashboard
Opens a local browser dashboard with four panels: Workflow Mode (ten selectable mode cards), Agentic Coding Environments (a multi-select across the seven supported tools, plus a read-only table showing whether the MCP server is registered in each config file), Authentication Tokens (GitHub token and LEX MCP access key, both shown masked, plus the remote MCP URL in full), and System Information. Saving a change syncs the config and stops the server so your coding tool restarts it on the new surface.
lex ai-dashboardlex ai-faq
Builds the LEX AI FAQ page from your installed package, writes it to a temp file, and opens it at the Prompt Builder. Nothing is fetched from the internet. Alongside the Prompt Builder it carries seven questions covering supported tools, upgrades, checking the server is running, the LEX Compatibility Score table, and a behavior map of the workflow.
lex ai-faqlex ai-issue-report
Creates a support bundle under .lex-ai-reports/ from your project environment, MCP config and Copilot state. Credentials are masked before anything is written — the bundle's manifest names every touched file and how many values were masked in it, and the command prints the count. It asks for confirmation first, then optionally submits the ZIP through the remote MCP and prints a ticket URL.
lex ai-issue-reportlex ai-update
Upgrades lex-mcp-local, then re-enters through the freshly installed code so the migrations that run are the ones the upgrade just delivered. Every step is re-runnable: legacy environment keys are removed, MCP entries are migrated to the unified entry point, the agent payload is re-materialised across every selected coding tool, and a half-finished interview left on an older tool surface is reconciled. It stops the running server so the next launch uses the new code.
lex ai-updatelex ai-verify
Verifies the AI asset directories in the current project and restores missing or modified shipped files when needed. It can align the MCP mode with the verified assets in interactive runs; MCP preflight calls use lex ai-verify --silent so stdio JSON-RPC is not polluted.
lex ai-verifylex ai-worktree
Prepares a second checkout so another LEX AI chat can work in parallel. One chat holds one working tree, so a second piece of work would otherwise compete for the same files. This cuts the run its own branch, seeds the checkout with the files git cannot carry — .env and the project-scoped MCP configs, both gitignored because they hold GITHUB_TOKEN — and prints the folder to open a chat in. That chat starts in brief, which asks what the run is and hands off to whichever mode the answer needs, so no mode is guessed before the interview. Needs a git repository with at least one commit. You do not have to run it: start a second chat and LEX AI notices the checkout is busy and prepares the same folder itself.
lex ai-worktree --name "add a dashboard"Related setup command
lex setup-with-ai belongs to the LEX App setup flow rather than to the AI command modules. Run it first when a project has not been wired for the MCP server yet. The command name uses hyphens; the underscore spelling you may see in older material is the Python module path, not a CLI command.
Two ways to say what you want
Run the interview, or build the prompt yourself. Both end in the same place: a contract specific enough to build from.
Let the interview do it: /lex-brief
Brief mode asks one question at a time, refuses filler, records who decided what, and writes .lex/contract.md — then names the mode to run next. You do not have to know the right shape of a prompt.
/lex-briefOr write it yourself: lex ai-faq
A five-step guided form covering foundation, product contract, evidence and boundaries, safety and failure, and proof. It offers ten build scenarios spanning nine LEX modes, scores how complete your contract is, and keeps drafts in your browser — nothing is sent to a server.
lex ai-faqIf you would rather just type something
A rough prompt is fine as a starting point. The assistant is expected to ask when a missing decision would materially change the output, so you are not required to get it right first time.
I want to [build / edit / review / document / test / deploy] a LEX app for [rough idea]. Interview me first if the scope is not clear enough to build from. Ask me for the missing details that matter.
What to expect while the AI works
The server keeps the workflow ordered; the IDE assistant coordinates; the mode-specific agents perform focused work.
Missing decisions surface
The assistant should ask when missing information would materially change the output.
Changes can re-route work
Forward-style modes can detect user edits to generated artifacts and re-run from the earliest affected step.
Artifacts explain the run
Plans, docs, technical maps, review reports, edit reports, MVP reports, and audit reports create handoff memory.
Parallel work
One chat holds one working tree. When a second piece of work turns up, LEX AI gives it a checkout of its own rather than letting two chats write the same files. If you only ever work in one chat, none of this appears.
You probably arrived here from a message
“Open a chat in this folder.” A tool returned ok: false with action_required: open_chat_in_worktree and a path. Nothing went wrong — LEX AI found this checkout already busy, prepared a second one, and is telling you where it is. Open a new chat with that folder as its root and carry on there.
“That run is still going.” The mode you asked for is one a second folder does not help. Wait for the named run, or close the chat holding it.
Start a second run yourself
Run it in your project when you already know more work is coming. It prints a folder — open a new chat with that folder as its root and approve the server your coding tool finds there.
lex ai-worktree --name "add a dashboard"The new chat starts in Brief
Not in the mode you were working in. A worktree exists because a second piece of work turned up, and that work has been through no intake. Brief asks what the run is, writes the contract, and hands off to whichever mode the answer needs — which is also why the branch is named lex-01 and not edit-01. Pass --mode only when you genuinely already know.
Finish and clean up
The run ends the way any run does — for Edit, at a pull request. Once it is merged, remove the folder with git worktree remove <folder>. It refuses if there is uncommitted work inside, which is the point. Nothing is removed automatically.
What can run alongside what
A refusal is a queue, not a failure
The serial modes each own something a second directory does not duplicate: one target environment, one wiki, one input format, one ordered sequence. Copying the files does not copy those. Two Test runs on a deployed project are refused outright, because there the test database is the live database. A run whose chat you closed stops blocking automatically.
Where the folder is
~/.lex-mcp/worktrees/<project>-<id>/<branch>/ — under LEX AI's own home, not beside your project, so a repository sharing a folder with a dozen others gains no neighbour. It needs a git repository with at least one commit and an onboarded project: the new folder is seeded with your .env and MCP configuration, which git cannot carry because they hold GITHUB_TOKEN.
Update LEX AI
Use the update flow when a new LEX AI version is available, then reopen the dashboard and confirm configuration.
Run the updater
lex ai-updateOpen the dashboard
lex ai-dashboardUse generated outputs for handoff
LEX AI produces files that help humans and future AI sessions understand what happened.
Intent
Capture requirements, architecture, data contracts, pseudocode, and compliance assumptions.
Code memory
Explains modules, models, relationships, and per-folder context.
Outcome
Audit, edit, review, reverse, or MVP reports summarize what changed and what still needs attention.
Git and GitHub behavior
Only forward-style modes own remote delivery. Flat modes leave outputs for the user to commit manually.
Commits, pushes, PR, merge
Creates branches, commits and pushes after steps, opens a PR, attempts squash merge, checks out default, and closes the tracking issue.
Same delivery mechanics
Uses forward Git/GitHub machinery but starts meaningful work at step 9.
Local git only
Creates local checkpoints when git is available, stores SHAs in the MVP manifest, never pushes.
No remote writes
May clone a GitHub URL, writes docs locally, but does not commit, push, branch, PR, or merge.
No remote writes
May clone into a temp edit directory, writes code/artifacts locally, and leaves delivery to the user.
No remote writes
May clone into a temp review directory, writes reports, and leaves committing/pushing to the user.
Current caveat
The current forward finalize path attempts to squash-merge after creating the PR. The code contains a production-mode helper intended to disable auto-merge, but the finalize path does not currently call it.
The LEX Compatibility Score
LEX AI runs on whichever model your coding tool is driving, and they are not equally good at it. The LEX Compatibility Score (LCS) holds LEX AI fixed and varies the model, to publish which ones drive it well.
It scores models, not LEX AI
This is the common misreading. LCS is not a quality score for the product — the artefacts are the constant, and the model is the variable.
Half probe, half published benchmarks
One 0-100 number: 50% a LEX-fidelity probe, 50% published vendor tool-use benchmarks. The benchmark half only counts once at least half of that weight is populated, so a single cherry-picked figure cannot move a ranking.
Whether the model goes looking
The probe brief never states a LEX rule. Every rule is discoverable only from the shipped docs, so what is being measured is whether the model reads them rather than assuming Django defaults.
With operational guidance
Recommended, Supported, Usable with supervision, and Not recommended. Four hard gates — including producing no project output, protocol violations and unsafe git — drop a model to the bottom regardless of its weighted average.
Confidence is derived, not asserted
Confidence comes from the number of graded runs. Checks that did not decide are excluded from both sides of the fraction rather than counted as failures, so a partial evaluation reads as partial.
Where to read the current table
Run lex ai-faqand open the "Which AI models work best" question. The table is generated from the evaluation log shipped inside your installed package rather than hand-written, so the published ranking cannot drift from the recorded evidence. The scoring rubric has since moved to a new version, and every published record is still awaiting its re-run — so the page currently recommends no model outright and says so.
lex ai-faqTroubleshooting and recovery
When an MCP tool returns ok: false, stop the workflow and surface the troubleshooting payload to the user.
Stop immediately
The IDE assistant should not keep calling tools, running shell commands, changing code, or trying git workarounds.
Show the user what happened
Present the structured troubleshooting details: summary, what happened, error detail, resolution steps, and how to retry after resolution.
Retry the same tool
After the user resolves the problem, retry the same MCP tool call. For stale-tool payloads, refresh the IDE tool list and switch modes if a suggested mode is provided.
Silent deterministic fixes
Commit summary cleanup, empty commit handling, and known small repair cases can be handled by the server without interrupting the user.
Workflow halts
Credentials, permissions, network failures, missing paths, GitHub errors, git conflicts, stale tool surfaces, corrupted state, and unknown errors require user action.
What support can diagnose
LEX AI emits operational signals that help diagnose common failure sources. This list is intentionally not exhaustive.
Preflight and configuration issues
Missing tokens, project path problems, server startup failures, mode mismatch, and environment configuration drift.
Step and run state
Workflow start/resume state, step request/completion progress, stale runs, manifest reconstruction, and finalization problems.
Re-execution triggers
User edits to generated files, new input spreadsheets/CSVs, step ownership mapping, and whether re-running an earlier step is expected.
Tool-list mismatch
Mode switches, cached IDE tools, stale tool calls, active mode, suggested mode, and refresh/retry instructions.
Scan and questionnaire coverage
Static scan coverage, parse issues, questionnaire generation, user-required answers, and documentation gap flow.
Backend calls and timing
Remote MCP calls, timeouts, network failures, GitHub/API failures, and structured error classes.
Frequently asked questions
Do I run the MCP server manually?
Usually no. The setup flow configures the IDE to run the local MCP server for the project. Use the dashboard to verify mode and configuration.
Why does the docs hub switch topics instead of scrolling?
Users typically arrive with a specific question. The docs app keeps navigation visible and swaps content in place.
Can I edit files during a forward run?
Yes. Between steps the server diffs the working tree, attributes each touched file back to the step that produced it, and rewinds to the earliest affected step — committing your edits first so the tree stays clean. Adding a new data file re-triggers from the input/output step.
Which coding tools does LEX AI work in?
Seven: GitHub Copilot in JetBrains IDEs, in VS Code and in the CLI, plus Cursor, Claude Code, OpenAI Codex and Windsurf. Each gets the MCP server registered in its own config format and the agent payload in its own native layout.
Do I have to know what I want before I start?
No. That is what brief mode is for — it interviews you, refuses vague answers with a sharper follow-up, and writes the contract the build modes work from. You end the interview whenever you like; anything unanswered is recorded as a named gap rather than invented.
Does LEX AI need to run commands in my terminal to read my data?
No. Every mode can read CSV, TSV, TXT, XLSX, XLSM, XLS and PDF files server-side and return them as markdown, so schema discovery works even in tools where a shell is unavailable or sandboxed.
Copied