Version control overview
On this page
Version control overview
Automatic change history for your whole project — once it's recording, every edit is captured, attributed, and revertable, with no commits to manage. · Optional
There's nothing to configure and nothing to commit: once version control is recording on a project, VibeMap captures changes in the background. The one thing worth knowing up front is when it starts — see When history starts recording below.
Think of it as Git for your project specification, built into the editor. You never commit anything; VibeMap captures changes for you.
Why it matters
A project goes through hundreds of small edits between the first generation and a handoff-ready spec — the conversational agent adds features, AI regenerations rewrite sections, you tweak personas by hand, your IDE agent adds acceptance criteria via MCP. After a long session it's easy to lose track. Version control answers four questions on demand:
- What changed? — a timeline of every edit, generation, and agent operation.
- Who changed it? — every change is attributed to you, a teammate, the AI, the MCP tool, or a system process.
- What exactly did it touch? — open any version to see its per-entity create / update / delete diff.
- Can I get the old version back? — yes, one click. Reverting is non-destructive: your current state stays in the timeline, so you can always come back.
When history starts recording
Version control is a per-project switch, and it starts off. A project only begins recording once something turns it on, and in practice that's the conversational agent: the first time the agent executes a change on a project, it enables version history for that project and everything from then on is captured — your own hand edits and regenerations included, not just the agent's work.
Two consequences worth knowing:
- The agent is a Pro-and-above feature. On Free and Starter there's normally nothing to switch version control on, so hand edits on those plans may not be recorded at all.
- It isn't retroactive. Edits made before the switch flipped aren't in the timeline. What you get on day one is a genesis version plus everything after it.
If the History tab is empty on a project you've been editing, that's what you're looking at — not lost data. Ask the agent to make a change (even a small one, like renaming a feature) and the timeline starts from there. If you're on Free or Starter and want history, upgrading to Pro is what unlocks the agent that turns it on.
What gets tracked
Once a project is recording, every mutation to the following content is captured:
| Area | Tracked entities |
|---|---|
| Features | feature cards (name, description, priority, complexity, effort, value) |
| User stories | the story cards under each feature |
| Acceptance criteria | given / when / then triples, including sprint assignment |
| Personas | persona cards (name, role, demographics, goals, pain points) |
| Pages & sections | page rows and the section tree inside each page |
| Page links | navigation links between pages |
| Schema | tables, columns, access rules |
| Business case & financial analysis | the research write-ups on the project |
| Colour schemes | brand colour sets |
| Project context & prompt | context additions and edits to the project prompt itself |
Not tracked (for now): account settings, billing, team membership, API keys, file structure / pseudocode, and uploaded reference files.
How changes are grouped
Related edits made close together bundle into a single changeset — a unit of work, like a Git commit — so the timeline stays readable. A changeset gathers edits over roughly a 5-minute window; after a pause, VibeMap closes it, captures a snapshot of your project at that moment, and the next edit starts a new one.
Grouping respects who did the work:
- You editing in the UI for a few minutes → one changeset attributed to you.
- The conversational agent running a multi-step operation → one changeset attributed to the AI.
- A batch regeneration (e.g. "generate all user stories") → one changeset for the batch.
- Your IDE agent calling VibeMap via MCP → one changeset per tool call, attributed to MCP.
The actor types
Every version is tagged with who made the change, with a colour-coded badge:
| Badge | Actor | Meaning |
|---|---|---|
| you (blue) | The logged-in user | An edit you made — in the UI or via the agent |
| user (blue) | Another teammate | An edit by someone else on a shared team project |
| AI (violet) | AI pipeline | A regeneration or large AI-driven update |
| MCP (emerald) | Your IDE agent | A change pushed in via the VibeMap MCP server |
| system (zinc) | System process | Internal automation, e.g. a backfill or revert |
Where it lives
Version control is the History tab at the top of every project. Open it to browse the timeline, inspect any version's diff, rename changesets, and revert.
💡 Tip: The conversational agent's edits are wrapped in their own changesets, so anything the agent does is fully revertable — you can undo an agent operation the same way you'd undo your own edit.
⚡ Power-user hints
- Snapshots power one-click revert. VibeMap stores a full snapshot when it closes a changeset. A few entries never get one — historical versions imported when version control was switched on, and any changeset still open — and those are marked "No snapshot — read only" (you can still view the diff, just not revert directly to that point).
- Rename as you go. Auto-titles are generic. Renaming a changeset to "Added admin panel features" costs nothing and makes future-you far faster at finding a rollback point — see Viewing history.
↔ The traditional way
A hand-run spec lives in docs and tickets with no change history — when something gets overwritten, there's no undo and no record of who did it. Engineers get this from Git, but only for code. VibeMap brings the same safety net to the specification itself, automatically, without asking you to commit.
What's next
- Viewing history → — read the timeline and inspect a version's diff.
- Reverting changes → — roll back safely and know exactly what's restored.