Checkpoints

Checkpoints are snapshots of your session at a specific point in time. They record the full task state, the git state, and which files had uncommitted changes.

Creating a Checkpoint

$ pas-agent checkpoint "Implemented login endpoint"
Checkpoint #3 saved: Implemented login endpoint
  Files with uncommitted changes: 4

Each checkpoint records:

A message describing the milestone
The current git branch and commit
Files with uncommitted changes (staged, unstaged, and untracked), each marked as added, modified, deleted, renamed, or untracked
A snapshot of the full task state
A timestamp

Listing Checkpoints

$ pas-agent list
Checkpoints for my-project (3):
    1. 2026-09-17 04:30:00 UTC  Set up project structure  (6 files)  [abc1234d]
    2. 2026-09-17 04:35:12 UTC  Implemented login endpoint  (3 files)  [abc1234d]
    3. 2026-09-17 04:39:40 UTC  Added password hashing  (1 file)  [9f8e7d6c]

How Checkpoints Are Used

When you export, the context file includes the most recent checkpoints and the files changed at the latest one:

## Files Changed (as of last checkpoint)
- `src/auth/hash.rs` (untracked)
- `src/auth/mod.rs` (modified)

## Checkpoint History
- **2026-09-17 04:30 UTC** — Set up project structure
- **2026-09-17 04:35 UTC** — Implemented login endpoint
- **2026-09-17 04:39 UTC** — Added password hashing

To keep context files small, only the last 10 checkpoints and 50 files are exported. Some agents limit how much of an instruction file they load. The full history stays in session.json.

Stale Checkpoints

A checkpoint is a snapshot, so edits made afterwards are not in it. PAS-Agent compares the current git commit and changed files with the latest checkpoint. The checkpoint counts as stale if the commit differs, or a file is new, no longer changed, has a different status, or was edited again (each changed file is stored with a fingerprint of its content). Context files that pas-agent export wrote, meaning files holding a complete PAS-Agent block, are ignored in this comparison. After a commit that only moves HEAD, the warning reads HEAD moved instead of counting files.

$ pas-agent status
...
⚠ 3 files changed since the last checkpoint (2026-10-09 14:20 UTC). Run `pas-agent checkpoint` to update.
    src/auth/hash.rs (untracked)
    src/auth/mod.rs (modified)
    src/old.rs (no longer changed)

pas-agent export prints the same warning on stderr but still exports. The context file gets a short section so the next agent knows the checkpoint is not current:

## Changed Since Last Checkpoint
The working tree has moved on since the last checkpoint (2026-10-09 14:20 UTC), so the sections above may be out of date:
- `src/auth/hash.rs` (untracked)
- `src/old.rs` (no longer changed)

Run pas-agent checkpoint to clear the warning. The list is capped at 50 files. Each file entry in a checkpoint gains an optional fingerprint field insession.json; checkpoints saved by older versions simply have none and are compared by path and status only. There is no warning before the first checkpoint or outside a git repository.

Storage

Checkpoints are stored inside .pas-agent/session.json, in order. Checkpoints taken in quick succession are all kept.

PreviousSessions NextPortable State