How Merget works

You sign in, you open your repo, you work with your coding agent like you always do. Merget commits the rest: not just what changed, but the prompts that drove each change. This page explains what's happening and what the pieces are called.

How Merget records your work automatically

You don't run commits yourself. A background committing daemon does it for you, the whole time the app is watching a repo. It records two kinds of work:

Your agent's sessions. When you install and launch Merget, it adds a small plugin to each supported coding agent it finds on your machine - Claude Code, Codex, Cursor, GitHub Copilot. The plugin reports each session's events - your prompts and the edits they produce - and the daemon turns them into history. See Your agent and Merget.
Your own edits. The daemon also watches the repo's files, so changes you make by hand - in the built-in Editor or any other editor - are recorded too, attributed to you rather than an agent.

You don't start or manage the daemon; the Merget app runs it for any repo it's watching.

Under the hood

Agent plugins emit events into the repo's .merget/ folder; the daemon reads those events, snapshots the file tree, and writes history. While an agent tool is running, the daemon attributes the resulting file changes to the agent; edits that arrive outside a tool run are attributed to you as human edits.

Automatic vs. manual commit

By default the daemon commits steps automatically: after your agent finishes or your edits settle, a step is committed on its own, and most of the time you never think about it. When you want control, there are two ways to commit by hand:

Manual commit mode. Turn it on in Settings. Edits are then held, and a Commit button appears in the repo toolbar - nothing becomes a step until you click it (or ask your agent to commit; see Your agent and Merget).
The CLI. merget commit creates a step from the current state, with matching commands for goals and prompts - useful for scripting or committing outside the app.

The three-level model

Everything Merget commits lands in a simple hierarchy:

Goal         "Add user authentication"
  Prompt     "Implement the login form"
    Step     one committed checkpoint: files + what changed

A goal is a collection of related prompts. Merget reads them together and names the objective they add up to - it's the unit you see on the Map.
A prompt is the instruction you give your coding agent - the prompt you send the LLM.
A step is one committed checkpoint: a snapshot of your files and what changed, carrying a short generated headline and description. One prompt can produce several.

Grouping is interpreted, and can improve

Which steps belong to which prompt, and which prompts make up a goal, is decided by Merget's processing service, which reads your prompts and diffs and organizes them into a meaningful story. Two consequences worth knowing:

There's a short delay between doing the work and seeing it grouped on the Map - raw activity may briefly appear as "pending."
Grouping can be revised. The organization is produced by an AI pass and isn't deterministic; titles and groupings can improve after the fact. The underlying steps and their contents never change - only the story told about them. (This is also why committing requires being online and signed in; see Sync & privacy.)

What committing requires

You're signed in. Nothing commits without an account - every step is attributed to an author.
You're online. Grouping happens on Merget's servers; during an outage, committing waits rather than guessing.
Your agent has the plugin installed. Added automatically when you install Merget; for an agent you added later, run merget plugins install (see Troubleshooting).

Next: The history model | Related: Sync & privacy | Your agent and Merget | Settings