Vibe coding multi-file state limits, traced to three specific failure points

The three points where multi-file state breaks

Calling them “limits” in the plural matters. They are three separate mechanisms with three separate fixes. If you only name the wall as “the model cannot see cross-file dependencies,” you cannot route around it.

1. Cross-turn drift, fixed by editing the working tree in place

The first failure point appears the moment your project has more than one file. You prompt “add a streak counter,” the builder fires the prompt list at the model, the model produces a new project from scratch, and your perfectly fine NavBar.tsx is now slightly different in three ways you did not ask for. The model is non-deterministic and the input is always the prompt list, so the file tree mutates each turn.

mk0r runs each turn through one persistent ACP session that lives for the lifetime of the E2B sandbox. The session-reuse logic is in src/core/e2b.ts around line 909: a sandbox lookup keyed by the session key in localStorage, with the same sessionId carried across turns. The agent edits files on disk in /app rather than producing the project again. Every cross-file reference you established in turn one survives turn five, because the file-system at turn five is not regenerated from a transcript; it is the file-system at turn four with edits applied.

2. The orphan-component bug, named honestly

Every multi-file vibe coder has hit this at least once. You prompt “add a star rating component.” The agent writes a clean src/components/StarRating.tsx. The preview refreshes. Nothing changes. The component file exists on disk, but nothing imports it into src/App.tsx, so React never renders it. The page is blank in the place where the rating was supposed to appear.

This is a real failure mode on every AI app builder we have tried, mk0r included. The mitigation lives in the agent's system prompt, not in code. The CLAUDE.md baked into the E2B template at /root/.claude/CLAUDE.md (you can read the source at docker/e2b/files/root/.claude/CLAUDE.md) tells the agent two specific things:

• “Always import and render new components in src/App.tsx. Components not imported from App.tsx will never appear on screen.”
• “After UI changes, navigate to http://localhost:5173 via Playwright MCP, take a snapshot, and check console messages. If the page is blank, verify the component is imported in App.tsx.”

The first instruction is a habit the agent is trained to apply before submitting a turn. The second is a recovery loop: after rendering, the agent checks its own output and self-corrects when the page is empty. Together they catch most orphans, but not all of them. When the agent does miss one, the fix is one prompt: “the StarRating is not showing up, check that App.tsx imports it.” The agent reads the file, sees the missing import, adds it, and the next turn renders correctly.

The honest framing is that this is a habit, not a guarantee. A vibe coder building seriously multi-file projects will hit one of these every couple of dozen turns. The right reflex when the preview goes blank is to suspect an orphan first, not a runtime error.

3. Partial undo, fixed by treating the whole tree as the unit

The third failure mode is the one that turns a salvageable mistake into a corrupt project. You undo a turn that touched seven files. The tool restores five of them and misses two, or restores all seven but produces a slightly different version because undo is implemented as a re-prompt. The result is a tree that never existed in the project's real history. From there, every new edit compounds the inconsistency.

mk0r treats the multi-file tree as the unit on both ends. Every successful turn writes a real git commit through commitTurn. The load-bearing line is git add -A: it stages every file modified, added, or deleted in /app at once. The resulting SHA is one snapshot of the whole project.

Undo is the symmetric operation: git checkout <sha> -- . where the trailing dot means “the entire working tree from this commit.” undoTurn at line 1731 reads historyStack[activeIndex - 1] and hands it to revertToSha at line 1691, which runs the checkout, stages, and commits the revert as an --allow-empty turn so the operation itself is part of the audit trail.

After undoTurn returns, ten files are byte-exact to the previous turn. App.tsx, every component, every hook, every util, the whole .env. The model is not consulted on undo, so the operation is deterministic, costs zero tokens, and cannot produce a tree that did not exist before.

And when you undo three turns and try a different idea, the slice at src/core/e2b.ts:1676 forks the history: historyStack = historyStack.slice(0, activeIndex + 1). Drop everything past the active pointer before pushing the new SHA. This is one line. Without it, undo plus a new prompt produces a tree that mixes the abandoned branch with the new one, and that is exactly when a multi-file project starts feeling unrecoverable.

What one turn looks like, end to end

The whole-tree-as-unit pattern is most legible in the sequence of one iteration turn. The user prompt enters one persistent session. The agent reads files from /app on demand, edits them in place, and the server commits the aggregate at the end.

Where the multi-file ceiling still bites

Whole-tree commits and persistent sessions push the wall back, but they do not erase it. The honest ceiling is the model's reasoning budget. When a project is small enough that the agent can fit the relevant files in context (or can read them on demand and reason about a few at a time), iteration holds up well. When the project grows past that, the agent starts forgetting cross- file conventions you established earlier: a Button styling pattern you set in turn three, a util signature you tightened in turn six, a hook contract you wrote in turn nine. The mitigation is the memory layer, mostly. The agent is told (in the same CLAUDE.md) to actively save user preferences and corrections as memories, and to read those memories at the start of each turn. That keeps intent stable past raw context length.

Past that, you stop vibe coding the project as one piece and start treating sub-folders as separate scopes: prompt only about the dashboard for a while, then only about the auth flow, then only about the admin panel. The agent does better when the unit it has to reason about is bounded. This is the same hack experienced engineers use when they delegate to a junior, and it works identically when the junior is an LLM.

The other ceiling is the envelope. mk0r generates working HTML, CSS, and JS or a Vite + React + Tailwind project. Multi-file iteration holds up well inside that envelope. It does not generate native iOS or Android, multi-user real-time state, or backend logic more complex than a single Postgres and a couple of Resend audiences can cover. If the requirement is in those zones, no amount of multi-file state hygiene fixes the mismatch; the right move is to bring in code and a developer.