pi-chrono

Session rollback for Pi Coding Agent — rewind your conversation and restore file state.

Overview

pi-chrono is an extension for Pi Coding Agent that enables time-travel-style session management. It automatically captures file states before each agent run and lets you roll back to any previous checkpoint, restoring both the workspace and the session context.

Perfect for when you want to undo AI-generated changes without losing your conversation history.

Features

• Automatic checkpoints: Captures file states before every AI turn
• Manual rollback: Use the /chrono command to restore any previous state
• Workspace restoration: Restores files to their exact previous condition
• Session forking: Creates a new branch from any point in your conversation
• Journal system: Tracks file operations (create/modify/delete) with full reversal support
• Blob storage: Content-addressed blob store for before/after file versions
• Rollback preview: Shows exactly which files will change before confirming
• Status monitoring: /chrono status for health & storage diagnostics
• Rollback diff inspection: /chrono diff to inspect rollback impact without restoring
• Garbage collection: Automatically cleans up obsolete checkpoint data

Installation

Using npm

pi install npm:pi-chrono

From GitHub

pi install github.com/stetaf/pi-chrono

Usage

Automatic behavior

pi-chrono works automatically once installed:

1. Before each agent run: Captures current file state (metadata + content hashes)
2. After the agent run settles: Creates a journal entry tracking all file operations
3. On session start: Loads existing checkpoints and garbage-collects old data

No configuration required — it just works.

Commands

Use the /chrono command with an optional subcommand:

/chrono            List and restore rollback points
/chrono status     Show chrono health & storage state
/chrono diff       Inspect file changes before rollback

Rollback (/chrono)

Running /chrono without arguments will:

• Display all available rollback points (with timestamps and message previews)
• Let you select which point to restore
• Confirm before proceeding
• Restore the workspace and fork the session at that point

Status (/chrono status)

Running /chrono status shows an overview of the chrono system:

• Number of stored checkpoints and their validity
• Journal disk stats (total / readable / corrupt files)
• Blob storage size
• Pending pre-manifest status

Diff (/chrono diff)

Running /chrono diff lets you inspect a rollback target without forking the session or restoring files:

• Select a rollback checkpoint using the same picker as /chrono
• See affected file counts grouped by operation kind
• See modified, recreated, and removed paths
• Use /chrono diff --full to show all affected paths
• Use /chrono diff --content to include compact text-level diffs for modified files

What happens during rollback?

When you roll back to a checkpoint:

• ✅ All files are restored to their state before that turn
• ✅ The session is forked at the selected entry
• ✅ You can continue working from that point forward
• ⚠️ The action cannot be undone — create new checkpoints after rollback if needed

Configuration

Ignore system

pi-chrono skips common non-essential directories and files when scanning the workspace. The ignore list covers multiple ecosystems:

.chronoignore

You can extend or override the default ignore rules by placing a .chronoignore file in your project root. The syntax is a gitignore-style subset:

*.log               # Ignore all .log files (anywhere)
.env                # Ignore files/directories named .env
custom/             # Ignore the custom/ directory entirely
node_modules/local  # Ignore a specific nested path

Supported syntax:

• Empty lines and # comments are ignored
• Trailing / — directory-only ignore
• path/with/slashes — matches relative to any ancestor
• *.ext — suffix-based ignore anywhere in the tree
• Plain names — directory or file name match

Rules from .chronoignore are merged after the default preset, so they can extend but not negate built-in rules.

Environment variables

Hashing tradeoff (mtime + size vs full SHA256)

By default, pi-chrono uses an optimistic caching strategy:

• When a file's mtime (modification time) and size are unchanged between turns, the file is considered unchanged and its previous SHA256 hash is reused.
• Only files where mtime or size differ are re-hashed to detect content changes.

Why: In normal AI turns, the vast majority of files are not touched — re-hashing every file after every turn would be wasteful.

Edge case: On some filesystems, mtime resolution is limited (e.g., FAT32: 2 seconds, HFS+: 1 second). A file could be modified twice within the same clock tick, producing identical mtime + size but different content.

• Default (fast): Trust mtime + size — sufficient for virtually all real-world workflows on NTFS, APFS, ext4, etc.
• Strict mode: Set PI_CHRONO_STRICT_HASH=1 to always compute the full SHA256, eliminating the edge case at the cost of performance.

How it works

pi-chrono uses three core mechanisms:

1. Pre-manifests: Captured before each agent run, containing file metadata (path, mtime, size, SHA256)

2. Journals: Created after the agent run settles, recording all filesystem operations:

   • modified: File changed (with before/after blob tracking)
   • created: New file added
   • deleted: File removed

3. Checkpoints: Persistent records linking journals to conversation entries for easy restoration

Storage structure

~/.pi/chrono/
├── blobs/              # Content-addressed blob store (before/after file versions)
└── sessions/
    └── <sessionId>/
        ├── state.json          # Checkpoint metadata
        ├── pending-pre.json    # Current turn's pre-manifest
        └── journals/
            ├── <entryId>.json  # Journal entries for each turn

Development

Prerequisites

• Node.js 20+ (with experimental strip-types support)
• TypeScript 5.9+

Scripts

# Type-check without emitting files
npm run typecheck

# Run smoke tests
npm test

Project structure

src/
├── checkpoints.ts      # Checkpoint listing and user-message entry type guard
├── commands.ts         # Chrono command parsing (subcommands: status)
├── config.ts           # Centralized configuration (concurrency, file size, strict hash)
├── diff.ts             # Diff summary and content diff generation
├── fs-utils.ts         # File system walking, hashing (SHA256), blob ingestion, mapLimit
├── ignore.ts           # Ignore system: IgnoreMatcher, default presets, .chronoignore parser
├── index.ts            # Extension entry point, event handlers, command registration
├── journal.ts          # File operation tracking, reversal, and blob management
├── paths.ts            # Directory constants, session path resolution, storage root setter
├── rollback-preview.ts # Rollback preview builder (operations, validation)
├── state.ts            # Checkpoint and pending-pre persistence (load/save)
├── status.ts           # Status report generation (checkpoint validity, disk stats)
├── types.ts            # Data structures (Checkpoint, Journal, PreManifest, etc.)
test/
└── smoke.ts           # Basic functionality tests

API Reference

Events listened to

• session_start: Initialize checkpoints and load state
• session_shutdown: Finalize pending checkpoints
• before_agent_start: Capture pre-manifest before AI turn
• agent_settled: Finalize journal after the complete agent run settles
• session_before_fork: Handle rollback when forking session

Commands registered

• chrono: List and restore rollback points (default)
• chrono status: Show chrono health & storage state