pi-rollback

Branch-aware rollback for pi

Install · Usage · How it works

When pi goes down the wrong path, roll back to the last relevant point, keep a concise summary of the detour, and continue from a cleaner context.

An extension package for pi — an AI coding agent that runs in your terminal.

pi-rollback gives both humans and agents a safe recovery workflow:

• go back to a better point in the session tree
• preserve only the lessons that still matter
• continue from a smaller, more relevant context window

Instead of deleting history, it uses pi's tree navigation and branch summaries. That makes rollback non-destructive, branch-aware, and recoverable.

Caveat: pi-rollback rewinds the agent's active session context, not your repo state. It does not automatically undo code, files, or patches the agent already generated during the abandoned detour. It only moves the conversation back to an earlier point in pi's tree and optionally leaves behind a compact summary.

---

Quick start

Install from npm:

pi install npm:pi-rollback

Then reload pi:

/reload

Start using it:

/checkpoint before-auth-refactor
/rollback {"targetLabel":"before-auth-refactor","continuePrompt":"Fix the auth bug with the smallest possible change."}

If you want to install straight from git instead of npm:

pi install https://github.com/uriafranko/pi-rollback

---

What's included

Extension tool	rollback — lets the agent recover when it realizes the current direction is not useful
Command	/rollback — rollback by recent count, checkpoint label, or exact entry id
Command	/checkpoint — mark the current leaf so future rollbacks are precise and easy

The commands are there for explicit human control, but the main idea is to let the agent cut its own stale context when it realizes the current branch is no longer helping.

---

Why this exists

Agent sessions often contain expensive detours:

• a refactor that turned out unnecessary
• a debugging theory that was plausible but wrong
• an optimization branch that drifted away from the real user goal
• repeated tool calls that added tokens but not durable value
• scope creep after a perfectly good checkpoint

If you keep pushing forward from there, the active context gets worse:

• more tokens are spent on irrelevant history
• the model gets anchored to the wrong plan
• the same dead end is more likely to repeat
• recovery gets harder the longer the branch drifts

A full restart is not great either, because it throws away the useful context along with the bad branch.

pi-rollback gives you the middle path:

keep the good checkpoint, keep the useful learnings, drop the detour.

---

Use cases

Situation	Why rollback helps	Best command
Bad refactor	Return to the clean pre-refactor state and keep only the useful findings	/checkpoint before-refactor then /rollback {"targetLabel":"before-refactor"}
Noisy debugging detour	Drop several recent low-value steps quickly	/rollback 2
Agent drifted from the user goal	Remove irrelevant branch context and resume on-task	rollback tool with continuePrompt
Risky exploration after a good state	Explore freely, knowing there is a precise way back	/checkpoint <label> before exploring
Need a pure rewind	Go back without leaving a new summary entry	/rollback {"targetLabel":"before-refactor","summarize":false}

---

Benefits

1. Cleaner context

After a rollback, the active branch is smaller and more relevant. The model sees less junk and makes better next-step decisions.

2. Preserves useful lessons

When summarization is enabled, the abandoned path is compressed into a short branch summary instead of being kept as raw noisy history.

3. Non-destructive

Rollback does not erase the old branch. The original path remains in pi's session tree and can still be revisited with /tree.

4. Good for autonomous agents

The rollback tool is LLM-callable, so the agent can recover on its own when it notices it is optimizing the wrong thing.

5. Better than “start over”

You keep the important checkpoint, the surviving context, and optional lessons learned, instead of throwing away the whole session.

---

Usage

1. Create a checkpoint

Use /checkpoint before risky work:

/checkpoint before-auth-refactor
/checkpoint before-db-migration
/checkpoint

If you omit the label, the extension generates a timestamp-based checkpoint name.

2. Roll back by label

This is the best and most reliable workflow:

/checkpoint before-auth-refactor
/rollback {"targetLabel":"before-auth-refactor"}

3. Roll back by recent count

This is fastest when the detour is recent:

/rollback
/rollback 2
/rollback {"dropMessages":3}

Count-based rollback uses recent completed checkpoints on the current branch. In practice, think of it as:

“undo the last few completed branch steps.”

4. Roll back by exact entry id

For advanced automation:

/rollback {"targetEntryId":"abcd1234"}

5. Continue automatically after rollback

Turn rollback into a recovery-and-resume step:

/rollback {"targetLabel":"before-auth-refactor","continuePrompt":"Take the smaller fix path and keep auth changes minimal."}

6. Choose whether to keep a summary

Default behavior keeps a concise summary of the abandoned branch:

/rollback {"targetLabel":"before-auth-refactor"}

Keep only the highest-signal learnings:

/rollback {"targetLabel":"before-auth-refactor","instructions":"Keep only validated findings and touched files."}

Pure rewind with no summary:

/rollback {"targetLabel":"before-auth-refactor","summarize":false}

---

Flow diagram

Good state reached
      |
      v
/checkpoint before-auth-refactor
      |
      v
Explore risky branch / refactor / debugging detour
      |
      v
Realize branch is no longer helpful
      |
      v
rollback tool or /rollback command
      |
      v
pi navigates back to target point in the session tree
      |
      +-----------------------------+
      | summarize = true            | summarize = false
      v                             v
Create branch summary              No summary entry
for abandoned detour               pure rollback move
      |                             |
      +-------------+---------------+
                    |
                    v
Smaller, cleaner active context
                    |
                    v
Continue from the earlier relevant point

---

How it works

The package is intentionally simple:

/checkpoint     -> labels the current leaf in pi's session tree
/rollback       -> resolves the rollback target
rollback tool   -> queues /rollback as a follow-up command
navigateTree()  -> moves the active branch backward
branch summary  -> optionally captures the abandoned path
continuePrompt  -> optionally resumes work immediately

Important design choice

Rollback does not mutate or delete the session JSONL history, and it does not revert your working tree for you.

Instead, it uses pi's existing branching model:

• move the active leaf backward
• preserve the abandoned path in the tree
• optionally attach a summary of what was learned

That is why the feature is safe, reversible, and compatible with /tree.

---

Install

From npm

pi install npm:pi-rollback

From GitHub

pi install https://github.com/uriafranko/pi-rollback

Manual install

cp -r extensions/pi-rollback ~/.pi/agent/extensions/

Then /reload in pi.

---

Development

Install dev dependencies and run the smoke check:

npm install
npm run check
npm run pack:check

Or:

bash tests/smoke.sh

---

License

MIT