@unilinear/pi-file-chat-tracer

A global Pi package that aligns conversation tree navigation with git file-state checkpoints.

It lets you explore aggressively with an AI coding agent while keeping a clean way to decide later:

• keep the generated files and return only the chat context with /tree;
• restore both chat and files;
• cherry-pick useful files;
• discard rough code but keep distilled lessons.

Why

Pi's /tree can move through conversation branches, while git can move through file history. This package records anchors between the two:

Pi leaf id  <->  git branch  <->  git commit  <->  checkpoint name

Tracer records are stored per repository under:

.git/pi-tracer/records.jsonl

They do not dirty your worktree.

Install

pi install npm:@unilinear/pi-file-chat-tracer

or from GitHub:

pi install git:github.com/unilinear/pi-file-chat-tracer

Reload Pi after installation if needed:

/reload

Commands

Start an exploration branch

/trace-explore <idea>

Creates exp/<idea>, makes a start checkpoint, and records the current chat leaf.

Manual checkpoint

/trace-checkpoint <name> | <reason>

Commits current file changes and links the commit to the current Pi leaf.

Status

/trace-status

Shows current branch, HEAD, dirty count, and recent file-chat anchors.

Restore files

/trace-restore <commit>

Runs a confirmed git reset --hard <commit>.

Agent tools

The package exposes two tools to the model:

• tracer_status: inspect current git/tracer state.
• tracer_checkpoint: create a rate-limited milestone checkpoint.

The checkpoint tool is intentionally conservative: it has a per-session limit and requires a meaningful reason.

/tree integration

The extension listens to Pi tree events:

• session_before_tree: injects recent tracer anchors into the tree summary.
• session_tree: records the new leaf id with the current git branch/commit.
• session_before_fork: if an anchor exists for a forked node, shows restore instructions instead of restoring automatically.

This gives /tree enough checkpoint history to align conversation return points with file return points.

Safety model

This package is deliberately conservative:

• no autonomous reset;
• no autonomous merge;
• no autonomous branch switching except explicit /trace-explore user command;
• destructive restore requires confirmation;
• agent checkpointing is rate-limited;
• tracer metadata is stored inside .git/, not committed to your project.

Recommended workflow

/trace-explore new-idea
# let the agent explore
/trace-checkpoint rough-v1 | first working prototype, still needs cleanup
# use /tree if context is polluted
/trace-status
# choose: merge, cherry-pick, reset, or keep only lessons

At the end of each exploration, classify the result:

A. keep code and lessons  -> merge/promote
B. keep only some files   -> cherry-pick
C. keep only lessons      -> write notes, reset/delete branch
D. discard all            -> delete branch

License

MIT