Troubleshooting

Problem → cause → fix, for the situations users actually hit. If your problem isn't here, the model pages — How Merget works and The history model — usually explain the behavior you're seeing.

Nothing is committing

Three preconditions have to hold before anything commits:

You're signed in. Nothing commits without an account — every step is attributed to an identity. Check the avatar in the sidebar.
Auto-track is on. If you declined the "Track prompts across coding tools?" dialog (or turned the toggle off later), Merget won't set itself up when your agent starts a session. Flip it back on in Settings.
The repo is set up. A folder Merget has never initialized has nothing watching it — see Creating your first repo.

Also check the tray menu: each linked repo has a per-repo committing checkmark, and quitting the app from the tray stops committing entirely.

My agent's sessions don't appear

Is the agent supported? Merget commits sessions from Claude Code, Codex, Cursor, and GitHub Copilot — see Supported agents. Other tools get file-change committing only (attributed to you), with no prompts or transcripts.
Was the agent installed after Merget was set up? Plugins install into the agents detected at setup time, so a newly installed agent isn't covered yet. Fix:
```
merget plugins install
```
Cursor specifically: a local Cursor setting can conflict with Merget's hooks. The app detects this and shows a Cursor Compatibility dialog — accept the one-click fix (it updates the setting and restarts Cursor). Until it's applied, Cursor sessions aren't committed reliably.

I edited files but no step appeared

Manual commit mode is on. Your hand edits are being held on purpose — look for the Commit button in the repo toolbar, or turn the mode off in Settings.
The edits are in ignored files. Paths matched by .mergetignore, .gitignore, or the built-in defaults are never committed — see Excluding files.
Otherwise, give it a moment: automatic committing waits a few seconds after you stop typing before committing a step.

History appears, but grouping is slow or looks odd

Grouping happens on Merget's servers: an AI pass reads your prompts and diffs and organizes them into goals, prompts, and steps. Two normal consequences:

A short "pending" stage. Raw activity can briefly show as pending before it lands in a goal.
Groupings aren't deterministic and can be revised after the fact. Titles and organization may improve later; the underlying steps never change.

During a service outage, committing waits rather than guessing — pending work is kept and retried, so nothing is lost silently, but new steps don't commit until the service recovers. See How Merget works.

Chat says it's unavailable

Chat needs three things: you're signed in, you're online, and the repo is registered with your account. Whatever is missing shows up as a notice attached to your message, and you can retry once it's fixed. Details in Chat.

Checkout refuses: "worktree dirty"

You have uncommitted changes on tracked files, and checkout won't overwrite them — it errors instead of clobbering. Either let the changes be committed (or commit them deliberately), or revert them, then check out again. Why checkout is strict about this is covered in The history model.

Stats are empty

Stats are computed from committed history, so a brand-new repo (or one where nothing has committed yet — see "Nothing is committing" above) has nothing to show. Work in the repo with committing on, and the numbers appear as steps accumulate.

`merget`: command not found

The CLI is part of the app, not a separate install: each time the Merget app starts, it makes the bundled merget binary available at ~/.merget/bin/. So, in order:

Launch the Merget app once — that refreshes the CLI link.
Check your PATH includes ~/.merget/bin (open a new terminal after the app's first run).
If you deleted the app, the CLI went with it — reinstall the app to get both back. See the CLI reference.

Next: FAQ · Related: Your agent and Merget · How Merget works