Checkpoints and agent sessions
When you work on a branch on your own Mac, alone or with Claude Code or Codex, Revue keeps a history of the work as checkpoints and follows each agent session in the checkout. This page explains when that happens and what the session states and Addressed mean.
When checkpoints are recorded
Section titled “When checkpoints are recorded”On a local branch, snapshots are called checkpoints. They’re the same thing: a checkpoint is a snapshot of local work. Revue records one when:
- The branch moves. When Revue reads the branch and finds its tip or its base has changed since the last checkpoint, after a commit, an amend or a rebase, it records a new one. A rebase that changed no code is marked Rebase only, and a rebase that did is marked Rebase.
- The pull request gets a push. A branch with a pull request also lists each push GitHub saw, marked Push.
- An agent finishes a turn. With the Claude Code plugin, Revue captures the
working copy the turn ended on and records it as a checkpoint labelled with Claude’s last message. A turn that ends
on an API error is recorded too, without the error as its label. Codex has no hooks, so it records one only when it
runs
revue checkpoint. - You run
revue checkpoint. It records the working copy as it is now.--messagegives it a label.
Checkpoints need a branch. When HEAD is detached, or the branch has no commits yet, none are recorded and Revue shows only the live working copy.
A claude -p run stops its background hooks when it ends, so its last turn is recorded when the next Claude Code
session in the same checkout starts or ends a turn. That checkpoint has no label. It’s recorded only while the commit
it was made on is still checked out, and a turn older than 7 days isn’t recorded at all.
A checkpoint isn’t a commit you can restore. It’s a record you can diff: pick one, or two for a range, the same way you pick snapshots of a pull request.
Session states
Section titled “Session states”A Claude Code session in a checkout Revue knows registers itself when it starts, and a Codex session when it runs
revue agent attach. The sidebar of a local tab
shows it with its state, and the context bar shows it as a chip while the sidebar is hidden.
| State | What it means |
|---|---|
| Working | A turn is running. Comments you send wait until it ends. |
| Idle | The session is waiting and listening, so comments you send reach it at once. |
| Idle (no recent activity) | A turn started, but Revue has heard nothing for over 10 minutes: no prompt, no turn end and no tool call. Claude Code runs no hook when you press Esc, so an interrupted turn reads this way, and so does one tool call that runs longer than that. The session hasn’t ended. |
| Not listening | The session’s wait for comments timed out. Comments you send arrive with your next prompt. |
| Disconnected | The session ended, or Revue hasn’t heard from it for 12 hours. It’s shown, but comments aren’t sent to it. |
The chip shortens the long one to “Claude quiet” so it fits.
Sending a comment never interrupts a turn. The comment waits until the turn ends and no tool call is running, or until your next prompt if the session stopped listening.
Addressed
Section titled “Addressed”When the agent deals with a comment, it replies in the thread and marks it Addressed with revue resolve.
Addressed is the agent’s word, not a verdict: check the change, then either
- Resolve it (⇧E), which closes it on this Mac, or
- choose Not addressed (E) to put it back in the agent’s list.
Only you resolve a thread. An agent can mark it addressed but never resolve it.
Local comments stay on this Mac and never go to GitHub. They say Not sent, never Pending.