Checkpoints
& Timeline

Overview

A checkpoint is a save point. Every checkpoint records the state of your session's workspace and your agent's conversation at the moment you took it. Checkpoints are not git commits, and saving one does not require a commit message or polluting your branch history with WIP entries.

The session's History panel shows every checkpoint as a node in a graph. The leftmost node is the project's base branch. From there, the line of nodes you have saved over time represents your timeline. When you restore an older checkpoint and keep working, a new line forks off in the graph. The DVR scrub bar above the terminal also marks every checkpoint as a tick, so you can line them up with the recording.

The system replaces several things you used to do by hand: git stash, manual git checkout of historical commits, careful interactive rebases to clean up WIP commits before pushing, and the "did I commit before switching branches" anxiety that comes with all of that.

Saving a Checkpoint

The session header shows a yellow n changes button next to Publish whenever there is uncommitted work. Click it - or press Mod+K - to open a composer with a title field (pre-filled with the current date and time) and an optional description. Press Enter to save, Escape to cancel.

You do not need to write anything thoughtful to save - the timestamp default is fine for fast saves. The title and description are searchable and show up in the History panel, so they are worth filling in for checkpoints you want to find later.

Restoring

Click any node in the History graph to Restore the session to that point. The workspace materializes the checkpoint's contents, the agent's conversation jumps back to the matching turn, and any commands you had running on the play button stop first. The project's init commands run again afterwards so dependencies stay in step with whatever the new checkpoint's manifests describe.

Restore is not a git operation. There is no detached-HEAD warning, no reset --hard, and no risk of losing work just because you forgot to commit before switching - any uncommitted changes are auto-saved as a WIP checkpoint on the line you walked away from before the new state materializes.

Before restoring, you can preview what a checkpoint contains by clicking View diff on the selected node. The graph swaps for a full-panel diff against the base branch so you can browse every changed file and see line-by-line what the checkpoint represents. Click Close to return to the graph with your selection and viewport intact.

Branching the Timeline

Restore an older checkpoint, make a different change, and save: the next checkpoint forks the timeline into a new line in the graph. Same session, same workspace path, no new branches to manage. You can have multiple parallel timelines visible in the graph at once, switch between them with a click, and pick the one you want to keep working from.

The leftmost base node is also a real restore target. Click it to reset the workspace to the project's base branch tip and start a fresh root in the timeline. Existing checkpoints stay in the graph as the abandoned line you can come back to.

Merging Tips

When you have parallel attempts at the same problem on different tips, you can fold one tip's changes into another without leaving the session. Select the tip you want to pull from in the History graph and click Merge into current. Files that diverged on both sides get conflict markers in the live workspace - resolve them in your editor, then save the result as a new checkpoint with the merge composer that opens.

If you have uncommitted edits in the workspace when you start a merge, those edits are saved as a WIP checkpoint first so they are not lost if the merge writes over the same files. The merge button is hidden on tips that descend from your current position (use Restore instead) and on tips that are already part of your current history.

The new checkpoint shows a Merged badge and points back at the source tip with a dashed line in the graph; the source tip itself shows a Folded in badge so you can see at a glance which lines have been combined. The timeline stays a single-parent graph - the source pointer is for layout only, not a second history edge.

Auto-WIP Captures

When you switch checkpoints with uncommitted work in the workspace, the work is saved automatically as a WIP checkpoint on the line you walked away from. WIP captures show in the timeline graph as tip nodes - the abandoned head of the path you left - so you can find them at a glance. Click a WIP node to bring those changes back; the restore consumes the WIP so abandoned auto-saves do not pile up.

WIP captures stay on your machine. They are never uploaded to the cloud and never visible to other devices on your account.

Publishing

Checkpoints are not commits, so when you are ready to share your work with the team you Publish it. Click the Publish button in the session header or press Mod+P.

Publishing projects whatever checkpoint you are currently on as a single clean commit on top of the base branch and force-pushes it to the session's branch on the remote. The team sees one tidy commit per publish, even if you took fifty checkpoints to get there. Republishing after more checkpoints overwrites the remote branch with the new projection - no rebase, no squash-merge dance, no cleanup.

The Publish button only appears when there is something new to publish: a clean workspace at a checkpoint that has not yet been pushed. With uncommitted work, the "n changes" button takes its place so you can save a checkpoint first.

Base Sync

The anchor: where your session sits on the base

Every session is anchored to a specific commit on its base branch. The anchor is the leftmost node in the timeline graph - "Base" badge, real commit message, author, short hash, time. That commit is the starting point your saved checkpoints build on top of. Restore takes you back to it; Update from base moves it forward.

You don't pick the anchor when you create a session - Taskeract records whichever commit the project's base branch was at when the session was started. Going forward, the anchor only moves when you explicitly run an update.

When the base moves

The team merges into the base branch all day; that movement doesn't disrupt your session. Taskeract notices the gap on the next background fetch and surfaces two signals:

• An amber dot on the session's sidebar entry, so you can spot behind-base sessions at a glance across the project.
• An amber Update from base pill in the session header, in the same slot where Publish, Create PR, and Merge & Push usually live.

While the session is behind base, the publish actions step aside - that pill takes their place because shipping a stale anchor would push outdated work to the team. Your local work continues unchanged: the agent runs, you capture and restore checkpoints, and uncommitted edits in the workspace stay yours. Only the team-visible actions are gated.

Updating from base

Click Update from base in the header (or click the base node in the History timeline and choose the same action). A focused update view opens with your timeline graph as the centerpiece.

Click Start update and Taskeract walks the chain. Each checkpoint animates through the states - pending, processing, done - so the graph itself is the progress indicator. There is no separate progress bar to interpret. Compatible edits between your work and the new base apply silently: untouched files come along for free, renames on one side combined with edits on the other are merged for you, additions that don't overlap stack cleanly. The agent's conversation history rides with the timeline so the run picks up coherently after the update.

Cancel at any time. Whatever the walk already absorbed stays applied; the rest is just queued for next time. The session does not get into a half-applied state - the orchestrator finalizes per-checkpoint, so each one is either fully applied to the new base or still pending.

Resolving conflicts

When the walk hits a checkpoint where Taskeract isn't sure, it stops on that node and the node glows rose on the graph. A resolution panel appears below the timeline listing the conflicting files. For each file you can take the merged result (when both sides' edits combine cleanly), keep yours, take theirs, or skip and come back later. Click Continue update once every file has a decision and the walk resumes from the next checkpoint.

Expand a file to see your version and the new one side by side, so you can read exactly what's different before deciding. The Accept button reads as the action you are taking - "Apply edit to new location," "Accept both additions," "Propagate rename" - so you always know what you are saying yes to. When Taskeract has a confident answer for a region of the file, it shows that answer with a one-click Accept; you only have to think about the parts that genuinely need a human call. Prefer everything to surface for review first? Set conflicts.automation to suggest-only or off in the config.

Dropping branches before the update

You can prune your timeline before starting the walk. Select any checkpoint in the graph and click Drop in the action panel - the subtree that's about to disappear (that node plus every descendant) lights up rose so you can preview the cascade before confirming. Drop is unavailable on the base node and on the active tip, since those are the two checkpoints the session can't function without.

Drop only removes the saved snapshots from the timeline; it never wipes your editor. Any work that lived in those checkpoints, plus anything you had in progress, becomes uncommitted changes you can review in the Changes tab and decide what to capture or discard. The drop syncs to every device on the session - and when a teammate or another machine drops a branch you happen to be working on, your timeline updates automatically: the dropped checkpoints disappear from the graph, the active tip falls back to the surviving parent, and the work moves to the Changes tab. Your editor stays exactly where it was, same files, same scroll positions.

Working in parallel

The update modal is per-session: while one session is updating, you can open any other session in the sidebar and keep working there. Only one device updates a given session at a time - if a teammate or another machine of yours starts the same update, the second one is locked out until the first finishes or cancels, so two devices can't fight over the same chain replay.

Repairing a legacy session

Sessions created before Taskeract started recording the anchor open into a one-time picker. The list shows recent commits on the base branch with a count badge per row indicating how many files would appear as workspace changes if the session were anchored there - a count of zero means that commit is an exact match (the workspace and saved checkpoints replay cleanly) and is almost always the right answer. Pick the matching commit and the session is repaired going forward; this won't happen again for any session you create afterwards.

Sessions That Travel

On the Pro add-on, every saved checkpoint is available from any device on your account and from anyone in your organization. Open the same session from another machine - or from a teammate's machine - and the timeline arrives: checkpoint titles and descriptions, the agent's conversation history, and the recording, with the workspace materialized at the latest saved checkpoint. New checkpoints saved on any device flow into the others continuously.

The team angle is the strongest one: when you review a pull request, you can open the actual session that wrote it and see the agent's full conversation, the timeline of decisions, and the recording. When you pick up an issue someone else started, the agent picker shows their existing session as a one-click attach. See Opening a Session from Anywhere for the full flow.

In-flight uncommitted work stays on the device where it was taken. WIP captures are local only - they exist as a per-device safety net. To make work available to the rest of the team, save a checkpoint.

All session data is end-to-end encrypted on your device before it leaves your machine. The cloud cannot read any of it - only devices on your account or organization hold the keys.

Agent-Proposed Checkpoints

Your agent can take checkpoints too. When the agent decides a moment is worth saving - finished a feature, about to try a risky refactor, end of a working chunk - it proposes a checkpoint with its own title and description. The composer opens pre-filled with a "Pre-filled by agent" hint so you can edit before saving, accept as-is, or cancel.

This means the agent can take meaningful save points without polluting your git history with WIP commits. The full granularity stays in the timeline; only the published commit ever leaves your machine.

Multi-Attempt Iteration

Agents can also navigate the timeline themselves: see every checkpoint in the session, restore the workspace to any of them, and save the current uncommitted state as a tip. This lets you say "give me five different ways to do X" and have the agent branch off the same starting point five times - each attempt becomes a sibling tip in the timeline graph for you to compare and pick from. See Multi-Attempt Iteration in Agent Capabilities for the full pattern.