{ "archive_path": "archive/1791929114.130773", "base_url": "github.com/nicchia-code/trama", "basename": "trama", "bookmarked_date": "2026-10-13 22:05", "canonical": { "archive_org_path": "https://web.archive.org/web/github.com/nicchia-code/trama", "dom_path": "output.html", "favicon_path": "favicon.ico", "git_path": "git/", "google_favicon_path": "https://www.google.com/s2/favicons?domain=github.com", "headers_path": "headers.json", "htmltotext_path": "htmltotext.txt", "index_path": "index.html", "media_path": "media/", "mercury_path": "mercury/content.html", "pdf_path": "output.pdf", "readability_path": "readability/content.html", "screenshot_path": "screenshot.png", "singlefile_path": "singlefile.html", "warc_path": "warc/", "wget_path": "github.com/nicchia-code/trama.html" }, "domain": "github.com", "extension": "", "hash": "15WEFBJ9DWG1RYXT1ZF6", "history": { "archive_org": [], "dom": [], "favicon": [ { "cmd": [ "curl", "--silent", "--location", "--compressed", "--max-time", "120", "--output", "favicon.ico", "--user-agent", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36 ArchiveBox/0.7.4 (+https://github.com/ArchiveBox/ArchiveBox/) curl/curl 8.14.1 (x86_64-pc-linux-gnu)", "https://www.google.com/s2/favicons?domain=github.com" ], "cmd_version": "curl 8.14.1 (x86_64-pc-linux-gnu)", "end_ts": "2026-10-13T22:08:48.376953+00:00", "index_texts": null, "output": "favicon.ico", "pwd": "/data/archive/1791929114.130773", "schema": "ArchiveResult", "start_ts": "2026-10-13T22:08:47.782438+00:00", "status": "succeeded" } ], "git": [], "headers": [ { "cmd": [ "curl", "--silent", "--location", "--compressed", "--head", "--max-time", "120", "--user-agent", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36 ArchiveBox/0.7.4 (+https://github.com/ArchiveBox/ArchiveBox/) curl/curl 8.14.1 (x86_64-pc-linux-gnu)", "https://github.com/nicchia-code/trama" ], "cmd_version": "curl 8.14.1 (x86_64-pc-linux-gnu)", "end_ts": "2026-10-13T22:08:49.250834+00:00", "index_texts": null, "output": "headers.json", "pwd": "/data/archive/1791929114.130773", "schema": "ArchiveResult", "start_ts": "2026-10-13T22:08:48.382161+00:00", "status": "succeeded" } ], "htmltotext": [], "media": [], "mercury": [ { "cmd": [ "/app/node_modules/@postlight/parser/cli.js", "https://github.com/nicchia-code/trama" ], "cmd_version": "1.0.0", "end_ts": "2026-10-13T22:09:17.463883+00:00", "index_texts": null, "output": "mercury", "pwd": "/data/archive/1791929114.130773", "schema": "ArchiveResult", "start_ts": "2026-10-13T22:09:11.946247+00:00", "status": "succeeded" } ], "pdf": [], "readability": [ { "cmd": [ "/app/node_modules/readability-extractor/readability-extractor", "/tmp/tmpudc_w2lp", "https://github.com/nicchia-code/trama" ], "cmd_version": "0.0.11", "end_ts": "2026-10-13T22:09:11.939157+00:00", "index_texts": [ "Trama\nTasks \u00b7 Requirements \u00b7 Analysis \u00b7 Map \u00b7 Agents\nYour AI agent writes code fast. Trama makes sure it's the code you meant.\n\nWhen 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.\nTrama 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.\nSee it in action\nLet's add returns to a small online shop: the shop example that comes with Trama.\n1. Say what you want\nWrite 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.\n\nYour agent picks it up right away, in the chat or terminal you already use, and starts reading the map.\n2. Answer a few questions\nThe 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.\n\n3. See the change before any code exists\nWhen 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.\n\nOn the board, the Proposal lists every file it touches. Approve it, or reject it with a note.\n\n4. Watch it get built\nApprove, and the agent checks what changed against the code, one sub-agent per Machine, in parallel.\n\nTasks appear on the board as the agent prepares them.\n\nThe returns design became nine Tasks, grouped under it.\n\nClick Run this design, and the agent works through them while you follow along.\n5. Know when code and map disagree\nWhen the code does something the map doesn't say, or breaks one of your rules, Trama calls it a Drift.\nA 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:\n\nThe code may be wrong. The agent misread a Task, or a quick hand fix skipped a case: a bug.\nThe 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.\nBoth may be reasonable. Two valid answers to a question the map never asked: it's a decision only you can make.\n\nSmall details that change neither the diagram nor one of your rules aren't Drifts: Trama raises one only when the behaviour itself differs.\nEach 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.\n6. Set the rules once\nTech stack, design, data, business rules: write them once, next to the map, and the agent follows them on every task.\nRules 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.\n\nYes, it's slower than raw vibe coding\nTrama is still vibe coding: you describe what you want, and the agent writes the code. What changes is what happens in between.\nWith 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.\nThat time isn't lost. It's spent where it's cheapest:\n\nDeciding 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.\nNever 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.\nCatching 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.\nLetting 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.\n\nThe first feature is slower. The fiftieth isn't, because the app is still one you understand.\nIf 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.\nAlready have a project?\nPoint 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.\nWhat's in the name\nTrama 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.\nThat'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.\nIn 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.\nThe letters spell out what's inside:\n\nTasks: the work the agent picks up, on a board you can follow.\nRequirements: how your app must be built, written once and followed every time.\nAnalysis: the agent compares your code with the map and tells you where they disagree.\nMap: every situation your app can be in, drawn for you as a diagram.\nAgents: works with the one you already use: Copilot Chat, Cursor, Claude Code or omp.\n\nTry it\nTrama runs in VS Code and Cursor, on Linux (x64), macOS (Apple silicon) and Windows (x64, preview).\n\n\nInstall the extension. Download the .vsix for your platform from Releases, then run Extensions: Install from VSIX\u2026 from the command palette, or:\ncode --install-extension trama--.vsix\nThe trama command line comes inside the extension, so there's nothing else to install.\n\n\nPick your agent in Settings (trama.agent), before you initialize a project:\n\nchat (default): Copilot Chat in VS Code, or the chat in Cursor.\nclaude: Claude Code in a terminal. Also set trama.skillsDir to .claude/skills, so Claude Code finds Trama's skills.\nomp: omp in a terminal.\n\nTerminal agents must already be installed and on your PATH.\n\n\nOpen your project and run Trama: Open.\n\n\nChoose Initialize Project for a fresh start, or Import from Code for an existing app.\n\n\nClick Design\u2026 and describe your first feature.\n\n\n\nWindows is in preview. The win32-x64 build is not yet verified end to end on Windows 11 (VS Code and Cursor, omp and Claude Code, Windows PowerShell 5.1, PowerShell 7 and Git Bash); the manual check in docs/uat.md decides when the preview ends.\ntrama.exe is not signed. Windows SmartScreen or an antivirus may warn the first time it runs. The command line is distributed only inside the .vsix, as on the other platforms.\n\nSettings\nFor Claude Code, writing in Italian, a typical setup looks like this:\n\n\n\n\nSetting\nDefault\nWhat it does\n\n\n\n\ntrama.agent\nchat\nWhere Trama sends its instructions: chat, claude or omp.\n\n\ntrama.skillsDir\n.agents/skills\nWhere Initialize Project installs the agent skills. Use .claude/skills for Claude Code.\n\n\ntrama.language\nempty\nLanguage for the prose the agent writes (descriptions, Proposals, Tasks, Drifts), e.g. Italian. Code, names, titles and IDs stay in English.\n\n\ntrama.terminalLocation\npanel\nWhere terminal agents open: panel (terminal area, in the background) or editor (a tab beside your code).\n\n\ntrama.analysis\nempty\nModel for design requests, Drift resolution and import.\n\n\ntrama.scan\nempty\nModel for scans, including the sub-agents that compare each Machine.\n\n\ntrama.execution\nempty\nModel for implementing Tasks.\n\n\ntrama.autoScan\ntrue\nAfter you approve a Proposal, scan what it changed and create the Tasks.\n\n\ntrama.autoExit\ntrue\nClose an agent's terminal as soon as it's done.\n\n\ntrama.maxParallelAgents\n20\nHow many sub-agents the agent may run at once.\n\n\ntrama.submitWhileRunning\ndisabled\nenabled lets you start a run while another is in progress.\n\n\ntrama.driftAutoPilot\ndisabled\nLet the agent resolve Drifts on its own: enabled for non-critical ones, yolo for all of them.\n\n\n\nFor the three model settings, write the model name as your agent accepts it, or leave it empty for the agent's default. In the chat they pick the model of the new conversation: in Copilot, a model with that name; in Cursor, the conversation's starting model. Every setting except trama.autoScan, trama.skillsDir, trama.language and trama.submitWhileRunning lives in your user settings only, so it can't be overridden per workspace. All the details are in the extension README.\nHow it works\n\n \n flowchart LR\n subgraph repo[\".trama/ in your repo\"]\n M[Model]\n R[Requirements]\n W[Proposals \u00b7 Tasks \u00b7 Drifts]\n end\n E[Editor extension] -->|reads, renders| repo\n E -->|sends instructions| A[Your agent]\n A -->|loads| S[Skills]\n A -->|explores, writes through| C[trama CLI]\n C --> repo\n R -.->|generated into| S\n A -->|writes| Code[Your code]\n\n \n \n \n Loading\n\n \n\n\nEverything is plain Markdown in your repo. .trama/ lives next to your code and is versioned with it: the Model in model/, the Requirements in requirements/, and the work in proposals/, tasks/ and drifts/. No database, no cloud service, no account.\nThe Model is a set of state machines. A System is split into Features. Each Feature groups Machines, and each Machine is one file listing its States, the Events that move it, and where each move leads, with conditions written as plain prose. States can nest. Machines never call each other: they react to Events, emitted by other Machines or by Actors outside the System (the user, a payment provider, time). The Diagram is generated from these files and laid out automatically. It's read-only: to change it, you ask the agent for a Proposal, so the files stay the single source of truth. File format.\nRequirements become skills. Requirements are grouped into Areas (ui, tech, quality, data, rules, or your own), split into fragments. Each Area and fragment says when an agent needs it, and each section applies to the whole System or to one Feature, Machine or State. Whenever a Requirement file changes, Trama regenerates them as agent skills (trama-req--), with that \"when\" as the skill's description. The agent's own skill loader then pulls in only the rules that matter for the task at hand. Past a size budget, each Area becomes one index skill instead, so a large rulebook never floods the agent's context.\nAgents go through the CLI. The trama CLI is a single binary bundled with the extension. Agents use it to explore the Model (trama machine order, trama paths order Draft Shipped, trama search refund), check it (trama validate, trama analyze), and create Proposals, Tasks and Drifts. It never reads your code: comparing the Model with the code is the agent's job.\nSkills drive the workflow. trama init installs five agent skills into your project, each one step of the loop:\n\n\n\nSkill\nDoes\n\n\n\n\ntrama-design\nAsks you questions in rounds, then writes a Proposal\n\n\ntrama-scan\nCompares Model and Requirements with the code; files Tasks and Drifts\n\n\ntrama-implement\nTurns Tasks into code; files a Drift when the Model can't be followed\n\n\ntrama-resolve-drifts\nAsks you how to settle each Drift, then records your choices in one Proposal\n\n\ntrama-import\nDescribes existing code as Proposals\n\n\n\nNothing changes without you. A Proposal holds the full new version of every file it touches and must pass validation against the whole Model before you see it. Nothing changes until you approve it. Decisions such as approving, rejecting or resolving a Drift are yours: agents take them only when you explicitly ask. An open Drift blocks every Task about the same part of the Model until you resolve it.\nBuilt for parallel agents. A scan gives each Machine to its own sub-agent. Implementation runs hand out Tasks in groups that touch different parts of the Model. After you approve a Proposal, only what it changed is scanned again.\nThe editor never calls a model. The extension renders the Diagram, Board and Requirements, shows the agent's questions in its own panel, and sends instructions to the agent you choose. All the reasoning happens in your agent, with your subscription.\nLearn more\n\nWhat the words mean\nCommand line reference\nContributing\n\nLicense\nTrama is open source under the GNU AGPL v3: use it, change it and share it, as long as your changes stay open too.\nWant to use Trama in a closed-source product? Get in touch for a commercial license.\nCopyright \u00a9 2026 Luca Soda" ], "output": "readability", "pwd": "/data/archive/1791929114.130773", "schema": "ArchiveResult", "start_ts": "2026-10-13T22:09:08.624040+00:00", "status": "succeeded" } ], "screenshot": [], "singlefile": [], "title": [ { "cmd": [ "curl", "--silent", "--location", "--compressed", "--max-time", "120", "--user-agent", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36 ArchiveBox/0.7.4 (+https://github.com/ArchiveBox/ArchiveBox/) curl/curl 8.14.1 (x86_64-pc-linux-gnu)", "https://github.com/nicchia-code/trama" ], "cmd_version": "curl 8.14.1 (x86_64-pc-linux-gnu)", "end_ts": "2026-10-13T22:09:08.619324+00:00", "index_texts": null, "output": "GitHub - nicchia-code/trama \u00b7 GitHub", "pwd": "/data/archive/1791929114.130773", "schema": "ArchiveResult", "start_ts": "2026-10-13T22:09:08.542380+00:00", "status": "succeeded" } ], "wget": [ { "cmd": [ "wget", "--no-verbose", "--adjust-extension", "--convert-links", "--force-directories", "--span-hosts", "--no-parent", "-e", "robots=off", "--reject=js,mjs,woff,woff2,ttf,otf,eot,mp4,m4v,mov,webm,ogv,mkv,avi,flv", "--timeout=120", "--restrict-file-names=windows", "--page-requisites", "--user-agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36 ArchiveBox/0.7.4 (+https://github.com/ArchiveBox/ArchiveBox/) wget/GNU Wget 1.21.3", "--compression=auto", "--timestamping", "https://github.com/nicchia-code/trama" ], "cmd_version": "GNU Wget 1.21.3", "end_ts": "2026-10-13T22:09:08.536473+00:00", "index_texts": null, "output": "github.com/nicchia-code/trama.html", "pwd": "/data/archive/1791929114.130773", "schema": "ArchiveResult", "start_ts": "2026-10-13T22:08:49.257821+00:00", "status": "succeeded" } ] }, "icons": null, "is_archived": true, "is_static": false, "latest": { "archive_org": null, "dom": null, "favicon": "favicon.ico", "git": null, "media": null, "pdf": null, "screenshot": null, "singlefile": null, "title": "GitHub - nicchia-code/trama \u00b7 GitHub", "warc": null, "wget": "github.com/nicchia-code/trama.html" }, "link_dir": "/data/archive/1791929114.130773", "newest_archive_date": "2026-10-13T22:09:11.946247+00:00", "num_failures": 0, "num_outputs": 6, "oldest_archive_date": "2026-10-13T22:08:47.782438+00:00", "path": "/nicchia-code/trama", "schema": "Link", "scheme": "https", "snapshot_id": "7c3ba81b-d1ee-47ce-b76b-3eeec475cda2", "sources": [ "/data/sources/1791929114-import.txt" ], "tags": null, "tags_str": "", "timestamp": "1791929114.130773", "title": "GitHub - nicchia-code/trama \u00b7 GitHub", "updated": "2026-10-13T22:08:47.782010+00:00", "updated_date": "2026-10-13 22:08", "url": "https://github.com/nicchia-code/trama" }