Cyclotomy

Workspace checkpoints for the Pi Coding Agent session tree.

English · 中文

A Pi conversation can move through its history. A workspace cannot; it has only the present.

Cyclotomy lets them travel together. It quietly records the workspace as the conversation progresses and, when you return to another point in the session tree, restores the workspace saved there.

Install it, then use Pi as usual.

Install

Requires Node.js >=24.15.0, Pi Coding Agent >=0.84.0, and Git.

pi install npm:cyclotomy

Cyclotomy starts automatically in saved Pi sessions. --no-session and in-memory sessions are not supported.

pi update npm:cyclotomy
pi remove npm:cyclotomy

Use

Command	Purpose
/tree	Navigate Pi's session tree; Cyclotomy previews workspace changes before restoring.
/drift	See what restoring the current checkpoint would change.
/restore	Restore the current node's checkpoint.
/cyclotomy	Show status.
/cyclotomy pause / resume	Pause or resume this instance.
/cyclotomy enable / disable	Set automatic startup for future instances.

Restoring can overwrite and delete files. Review the preview before confirming; Escape cancels. You can keep the current files and continue working on a new branch of the conversation.

Each session node has at most one checkpoint. A node without its own checkpoint uses its nearest recorded ancestor. Incomplete captures never replace a saved checkpoint.

Your data

• Git ignore rules define the managed files in a Git worktree; .git is never captured or changed. Outside Git, supported files under the workspace are managed.
• Checkpoints are stored outside the workspace, normally in ~/.pi/agent/cyclotomy/. They are unencrypted and remain after uninstalling.
• Cyclotomy records observed workspace states. Keep using Git and independent backups.

No configuration is needed for normal use. See configuration and storage for optional settings and recovery details.