Trama – See your agent's changes as state machines before any code Trama, a tool from developer Nicchia Code, lets an AI coding agent write a plain-text state-machine map of an application that Trama renders as an always-current diagram before any code is written. In its shop example, adding returns generated nine agent questions, a Proposal showing new parts in blue and removed parts in red, and nine Tasks, with any mismatch between code and map flagged as a Drift that blocks further agent work on that part of the app until the user decides. Trama's stated trade-off is that every feature takes more steps than raw vibe coding, spending that time on decisions made before building. T asks · R equirements · A nalysis · M ap · A gents Your AI agent writes code fast. Trama makes sure it's the code you meant. When an agent writes most of the code, it's easy to lose track of what your software actually does. Every prompt adds behaviour nobody looked at. Trama gives you and your agent a shared map of your app : every situation it can be in, and what moves it from one to the next. The agent writes the map as plain text, and Trama draws the diagram from it, automatically and always up to date. You never drag a box or draw an arrow. The agent reads the map before it writes a line. Let's add returns to a small online shop: the shop example https://github.com/nicchia-code/trama/blob/main/examples/shop that comes with Trama. Write it the way you'd tell a colleague. One line is enough, or take a whole page. Send it from the tab's menu; closing the tab sends it too. Your agent picks it up right away, in the chat or terminal you already use, and starts reading the map. The agent asks only what it can't decide alone. For returns it had nine questions, starting with how a delivery should be modelled, since the 14 days start from it. Each one comes with the agent's recommendation already selected, so most of the time you just confirm. Skip the ones you don't care about: the agent uses its recommendation and lists it as an assumption for you to check. When the agent is done, pick its Proposal on the map: new parts in blue, removed parts in red. Here, returns bring in a new Actor, time, which closes the return window. The side panel sums up every decision and every assumption. On the board, the Proposal lists every file it touches. Approve it, or reject it with a note. Approve, and the agent checks what changed against the code, one sub-agent per Machine, in parallel. Tasks appear on the board as the agent prepares them. The returns design became nine Tasks, grouped under it. Click Run this design , and the agent works through them while you follow along. When the code does something the map doesn't say, or breaks one of your rules, Trama calls it a Drift . A Drift is not a bug report. It only says that the code and the map no longer tell the same story, and it doesn't decide which one is right: - The code may be wrong. The agent misread a Task, or a quick hand fix skipped a case: a bug. - The map may be out of date. You changed your mind while coding, or the code handles a case nobody thought to draw: the code is right, and the map should catch up. - Both may be reasonable. Two valid answers to a question the map never asked: it's a decision only you can make. Small details that change neither the diagram nor one of your rules aren't Drifts: Trama raises one only when the behaviour itself differs. Each Drift shows what happens, what should happen, and two to five ways to fix the code, with the agent's recommendation first. You pick one. Or you keep the code as it is, and the map is updated to match. Until you decide, the agent won't start any Task about that part of the app, so nothing new gets built on shaky ground. Tech stack, design, data, business rules: write them once, next to the map, and the agent follows them on every task. Rules grow with the map. The returns design added its own: the window ends at 23:59 on the 14th day after delivery, a return covers the whole order, and the refund is the full total. Each rule is tied to the exact part of the map it applies to, like order/Delivered . Trama is still vibe coding: you describe what you want, and the agent writes the code. What changes is what happens in between. With raw vibe coding, you type a prompt and code appears. With Trama, you answer questions, look at the change on the map, approve it, and only then does the agent write code. Every feature takes more steps, and you'll feel it. That time isn't lost. It's spent where it's cheapest: - Deciding before building. A question answered now is cheaper than a feature rebuilt later. Changing a line on the map takes a second; ripping out code that went the wrong way takes an afternoon. - Never explaining twice. The map and your rules stay in the repo. Every new session, every agent, every teammate starts from what's already decided, not from an empty chat. - Catching mistakes while they're small. A Drift flags code that went off the map as soon as it's scanned, before more features get piled on top of it. - Letting agents work in parallel. Because every Task is tied to a clear part of the map, several agents can build at once without stepping on each other. The first feature is slower. The fiftieth isn't, because the app is still one you understand. If you're hacking a weekend prototype you'll throw away on Monday, raw vibe coding is fine. Trama is for software you mean to keep. Point Trama at your existing code. The agent draws the map of what your app does today, and flags anything that looks wrong along the way. Trama is Italian for the weft : the thread a weaver passes back and forth through the loom until a pattern appears. Once the cloth is woven, the pattern holds. You can't change it by tugging at a single thread: a stray pull shows at once, and a new pattern has to be woven on purpose. That's the idea behind Trama. Your agent is a very fast weaver, and the map is the pattern. Every change to the design is woven in deliberately, as a Proposal you approve, and a thread pulled out of place in the code shows up as a Drift. In Italian, trama is also the plot of a story: what happens, in what order, and why. A map of every state your app can be in, and every event that moves it on, is exactly that. The letters spell out what's inside: - Tasks : the work the agent picks up, on a board you can follow. - Requirements : how your app must be built, written once and followed every time. - Analysis : the agent compares your code with the map and tells you where they disagree. - Map : every situation your app can be in, drawn for you as a diagram. - Agents : works with the one you already use: Copilot Chat, Cursor, Claude Code or omp. Trama runs in VS Code and Cursor, on Linux x64 and macOS Apple silicon . 1. Install the extension. Download the .vsix for your platform from Releases https://github.com/nicchia-code/trama/releases , then run Extensions: Install from VSIX… from the command palette, or: code --install-extension trama-