Parallel work

Running more than one LEX AI chat on the same project: when you get your own checkout, when you are asked to wait, and why.

A
Written By Atakan KayaLast updated 3 months ago

Parallel work

One chat holds one working tree. When a second piece of work turns up — a fix while a test run is going, a review beside an edit — both chats write the same files, and neither can tell which uncommitted line belongs to which run. LEX AI gives the second run a checkout of its own instead.

You do not have to set any of this up. If you only ever work in one chat, none of it appears.

You probably arrived here from a message

"Open a chat in this folder." A tool returned ok: false carrying action_required: open_chat_in_worktree and a path. Nothing went wrong. LEX AI found this checkout already busy with another run, prepared a second one for you, 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 — see What can run alongside what below. Wait for the named run, or close the chat that holds it.

Starting a second run yourself

Run this in your project when you already know a second piece of work is coming:

lex ai-worktree --name "add a dashboard"

It prints a folder. Open a new chat with that folder as its root. Your coding tool asks once to approve the MCP server it finds there; approve it, and that chat has its own LEX AI on its own branch.

Both routes call the same code, so there is one behaviour to learn. The command only saves you a round trip.

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 — at most a sentence typed into the chat that got moved aside. Brief is the front door: it asks what the run is, writes the contract, and hands off to whichever mode the answer needs.

This is also why the branch is named lex-01 rather than edit-01. Which mode a run belongs to is the interview's own first question, because the same sentence can mean build, change, document or ship depending on what you already have. Pass --mode test if you genuinely already know; the branch then says so and the interview does not have to ask.

What can run alongside what

Combination

What happens

Several Edit runs, or Test beside Edit

Fine. Each gets its own checkout.

Review or Brief beside anything

Fine, and no second folder is needed — neither writes source.

Forward, Backward, Deploy, Input, MVP

One at a time. You are told which run is still going.

Two Test runs on a deployed project

Refused.

The serial modes are serial because each owns something a second directory does not duplicate: one target environment, one wiki, one input format, one ordered sequence of steps. Copying the files does not copy those, so a second checkout would not help — it would just let two runs damage the same single thing more quietly.

Two Test runs on a deployed project are refused outright rather than moved, because there the test database is the live database, and two suites would migrate and truncate the same one. Two Test runs are fine on a project with no deployment environment set.

A refusal is a queue, not a failure

It names the run in the way, and why a second checkout would not help. Nothing is lost and nothing is broken — the work simply has to happen in order.

A run whose chat you have closed stops blocking automatically. Most runs end by the chat being closed rather than by a formal finish, so a forgotten window never locks a mode out.

Where the folder is

~/.lex-mcp/worktrees/<project>-<id>/<branch>/

Under LEX AI's own home directory, not beside your project. A project that shares a folder with a dozen others does not gain a neighbour it did not ask for, and cleaning up is one directory. The <id> distinguishes two clones of the same repository, which would otherwise share a name.

Finishing a parallel run

The run ends the way any run does — for Edit, at a pull request. Once it is merged, remove the folder:

git worktree remove ~/.lex-mcp/worktrees/<project>-<id>/<branch>

It refuses if there is uncommitted work inside, which is the point. git worktree list, run from your project, shows what is still outstanding. Nothing is removed automatically.

Requirements

  • A git repository with at least one commit. A fresh git init has nothing to branch from.
  • An onboarded project (lex setup-with-ai). The new folder is seeded with your .env and the project's MCP configuration, because git cannot carry them — they are ignored for holding GITHUB_TOKEN, and without them the new folder would have no LEX AI at all.
  • A current lex-mcp-local. Run lex ai-update if in doubt.

If something looks wrong

Symptom

Cause

The new chat has no LEX AI tools

The server was not approved when your coding tool asked. Reopen the folder and approve it.

It says the repository has no commits

An empty git init. Commit something first, then run the command again.

The command is not found

lex ai-worktree ships with the LEX App package. Update it, then run lex ai-update.

Two runs' changes are mixed together

Both chats were in the same folder. Check the branch each chat is on; a parallel run should be on its own.

See also Handoff, Git and GitHub, and Edit.

Was this helpful?

Your feedback shapes what we write next.