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 do not add commits to your working branch, 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. Restoring an older checkpoint and continuing work creates a new line in the graph. Without session sync, that full multi-timeline graph stays local to this device. 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.

You can also fork a new session from any moment in the DVR recording, not just from a saved checkpoint. Scrub the recording back to the point you want to revisit and click Fork from here. A new session opens against the same project with the workspace and agent conversation set to that exact moment, so you can take a different path from a spot you never explicitly saved.

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 pushed to your Git remote 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.

If someone adds commits to that remote branch outside Taskeract, Publish pauses before overwriting them. You can import a simple straight-line set of remote commits into the timeline as External checkpoints, or discard those remote commits and publish the checkpoint you already selected. Merge commits are not imported automatically; Taskeract asks you to handle that branch outside the checkpoint timeline.

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.

Update from base works on the timeline you are currently using. Other timeline tips stay visible in the graph and show an Update badge when they still need to be replayed onto the current base. Restoring one of those tips opens the same update flow for that timeline first; after it completes, the restore continues onto the equivalent updated checkpoint.

Cancel at any time. The walk holds every change in a side-channel until it finishes, so cancelling reverts the entire run cleanly - the session is exactly where it was before you clicked Start. There is no half-applied state to recover from. Start over when you're ready.

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 keep yours, take the new base's version, ask the live agent to repair the files in the worktree, or hand-resolve in your external 3-way merge tool. Click Continue update once every file has a decision and the walk resumes from the next checkpoint. If you need to step away, Cancel update discards the run entirely - nothing has landed yet, so you can come back later and start fresh.

Update from base also pauses if the remote session branch has commits made outside Taskeract. Import or discard those remote commits first, then start the update. Imported external checkpoints contain the code changes from those commits, but not agent conversation history or recordings because that data was never captured by Taskeract.

The Tool button opens the file in your configured external merge tool with the base, your version, the new base's version, and a working merged copy. When you save and close, Taskeract picks up the result and marks the file resolved. Configure which tool to use in Settings > Appearance. Prefer fewer files to auto-resolve so you can see more for review? 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.

Sessions That Travel

With session sync, 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. With the Pro add-on, saving a checkpoint adds work to the timeline that travels between devices and teammates; use Publish when you want the session branch itself to reflect a specific checkpoint.

Session state lives alongside your code in the same Git repository on GitHub, GitLab, or Bitbucket when session sync is enabled. Saved checkpoints, the workspace at each checkpoint, and the cross-device timeline all ride on the Git hosting you already use - nothing extra to host, no separate sync service to trust. Without session sync, checkpoints stay local to the device, while Publish still updates the session's normal branch.

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 normal branch history with WIP commits. Without session sync, that full timeline is limited to this device; only an explicit Publish updates the branch on your Git remote. With session sync, the checkpoint timeline also syncs through your Git remote so other devices and teammates can open it.

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.