Version Control Overview
On this page
Version Control Overview
VibeMap automatically records every change made to your project — every feature added, persona edited, schema column renamed, page generated, or acceptance criterion tweaked — so you can review the history, see exactly what changed, and roll back to any earlier version of your project in one click.
Think of it as Git for your project specification, built directly into the editor. You never have to commit anything; VibeMap captures changes for you in the background.
Why Version Control?
A VibeMap project goes through hundreds of small edits between the first generation and a handoff-ready spec. The conversational agent adds features, the AI runs regenerations, you tweak personas by hand, the MCP tool fired from your IDE adds an acceptance criterion. After a long working session it is normal to lose track of what changed, who changed it, or when something you needed got overwritten.
Version control answers four questions on demand:
- What changed today? — scroll through a timeline of every edit, AI generation, and agent operation.
- Who made this change? — every change is attributed to a user, the AI, the MCP tool, or a system process.
- What exactly did that change touch? — open any version and see the per-entity create / update / delete diff.
- Can I get my old version back? — yes, one click and a confirmation. Reverting is non-destructive: the current state stays in the timeline as its own version, so you can always come back.
What Gets Tracked
Every mutation to the following project content is captured:
| Area | Tracked entities |
|---|---|
| Features | feature cards (name, description, priority, complexity, effort, business value) |
| User stories | the story cards under each feature |
| Acceptance criteria | given / when / then triples per story, including sprint assignment |
| Personas | persona cards (name, role, demographics, goals, pain points) |
| Pages | page outline rows (name, path, description, page type, design context) |
| Sections | the section tree inside each page (frames, text, layout properties) |
| Page links | navigation links between pages |
| Schema | tables, columns (data type, constraints, foreign keys), access rules |
| Business case | the business-case write-up on the project summary |
| Color schemes | brand colour sets |
| Project context additions | extra context blocks attached to the project |
| Prompt amendments | edits to the project prompt itself |
What is not tracked (for now): your account settings, billing, team membership, API keys, file structure / pseudocode (still being added), and uploaded reference files.
How Changes Are Grouped
Related edits made close together are bundled into a single changeset — a unit of work, similar to a Git commit — so the timeline stays readable. A typical changeset bundles every edit you make over a 5-minute window. After 5 minutes of inactivity, VibeMap closes the changeset, captures a snapshot of your project state at that moment, and the next edit starts a new one.
You can think of a changeset as "one sitting of edits." The grouping respects who did the work:
- You editing in the UI for 3 minutes straight → one changeset attributed to you.
- The conversational agent running a multi-step operation → one changeset attributed to the AI for that whole operation.
- An AI regeneration (e.g. "Generate all user stories") → one changeset for the entire batch.
- Your IDE agent calling VibeMap via MCP → one changeset per tool call, attributed to MCP.
The Four Actor Types
Every version in the history is tagged with who made the change. The actor badge on each timeline entry uses a colour to make this scannable at a glance:
| Badge | Actor | Meaning |
|---|---|---|
| you (blue) | The current logged-in user | An edit you made yourself — either in the UI or via the conversational agent |
| user (blue) | Another user | An edit made by a different teammate sharing the project (relevant for team workspaces) |
| AI (violet) | AI generation pipeline | A regeneration step or large AI-driven update (e.g. "Generate features") |
| MCP (emerald) | Your IDE agent via MCP | A change pushed in by Cursor / Claude Code / Windsurf calling the VibeMap MCP server |
| system (zinc) | System process | Internal automation, e.g. a backfill or revert operation |
What You Can Do With History
From the History panel you can:
- Browse the full timeline of versions, newest first.
- Rename any changeset — give it a meaningful title like "Added admin panel features" so future-you can find it.
- View the exact set of operations (create / update / delete) inside any version.
- Revert the entire project back to any version's state, with one click. The current state is never lost — it stays as its own version in the timeline.
The next two pages walk through each of these workflows step by step.
How Snapshots Work (Behind the Scenes)
You do not need to think about this to use version control, but it is useful background:
- VibeMap stores a full snapshot of your project state at the end of every closed changeset. This is what makes one-click reverts possible.
- Snapshots are stored compactly and only contain the in-scope project content above.
- Older snapshots are eventually pruned to keep storage costs reasonable, but revertable versions are kept available for a long time. The History panel marks any version that no longer has a snapshot as "No snapshot — read only" — you can still view its diff, but cannot revert directly to it.
Where Version Control Lives in the App
The History button sits at the top of every project page. Clicking it slides open the History panel from the right side of the screen.
You can also open it with the keyboard shortcut Cmd-H (Mac) or Ctrl-H (Windows / Linux).
Next Steps
- Viewing project history — how to read the timeline and inspect a version's diff.
- Reverting changes — how to roll back to an earlier version and what to expect.