🚚 pi-session-migrate — Session Migration for Moved Projects

@moguw/pi-session-migrate is a native Pi coding agent extension that migrates a project's Pi sessions after the project moves to a new path.

When you move a project directory, Pi still keeps that project's sessions under the old path. pi-session-migrate finds those "dangling" sessions (their header cwd no longer exists), groups them by old project path, and copies the group you pick into the current project — rewriting each session's cwd header so Pi opens them from the new location without the missing-cwd error.

✨ Features

• /migrate scans every session under ~/.pi/agent/sessions/ and finds "dangling" sessions whose header cwd no longer exists — no need to remember the old path.
• Groups dangling sessions by old project path, so an entire project's history migrates in one step.
• Every group is listed with advisory markers; nothing is filtered or auto-selected:
  • same name — the old project's directory name matches the current project (zero-cost match).
  • claim: … — a configured claim model judged the group (likely from this project / different project / unclear).
• /migrate <old-path> migrates a specific old path explicitly (supports ~ expansion).
• Rewrites each session's header cwd and parentSession, skips sessions whose id already exists in the target, and keeps the source directory as a backup.
• Historical message content is copied verbatim — never rewritten.

📦 Install

pi install npm:@moguw/pi-session-migrate

Try without installing permanently:

pi -e npm:@moguw/pi-session-migrate

For local development from the pi-ext repository root:

pi -e ./extensions/pi-session-migrate

🚀 Usage

/migrate                     Scan for dangling sessions and migrate the group you choose
/migrate <old-path>          Migrate sessions of a specific old project path
/migrate settings            Configure the claim model

/migrate (scan mode)

Scans every session directory under ~/.pi/agent/sessions/, finds sessions whose header cwd no longer exists on disk, and groups them by old project path. Every group is listed:

/Users/you/code/old-app   ·  9 sessions  ·  same name
/Users/you/code/old-demo  ·  3 sessions  ·  claim: likely from this project

Pick a group, confirm, and the sessions are copied into the current project. The source directory is kept as a backup.

When more than one old project is listed in the interactive TUI, press / to filter by project path. Use Up and Down to navigate the filtered groups, Enter to select, and Esc to clear the search; press Esc again to cancel the picker.

/migrate <old-path> (explicit mode)

Migrate a specific old path (supports ~ expansion). Useful when the old sessions directory still exists but the path is not dangling yet (pre-move), or when you already know the exact old path.

⚙️ Configuration

/migrate settings configures the claim model used for the claim: annotations:

{
  "model": "",
  "thinkingLevel": "minimal"
}

• model: claim model as provider/model. Empty uses the current session model.
• thinkingLevel: thinking level for the claim request.

The model runs only for groups that do not have a same-name match and only when a claim model is configured. Its verdict is advisory — you always choose.

🧠 Behavior

What a migration does for each copied session file (<timestamp>_<id>.jsonl):

1. Header cwd is rewritten to the current project path — without this, Pi throws a missing-cwd error on open.
2. parentSession references that pointed into the old project's session directory are rewritten to the new one.
3. Sessions whose id already exists in the target project are skipped and reported.
4. Message content is copied verbatim. Historical absolute paths inside messages are not rewritten.

Notes:

• The source session directory is left untouched (backup). Delete it manually once you have confirmed the migrated sessions work.
• Path trust (~/.pi/agent/trust.json) is intentionally not migrated — trust is a security decision for the current path, so confirm it yourself when Pi prompts.
• The session directory encoding mirrors Pi's internal layout (--<encoded-cwd>--). If the target directory already exists, conflict detection is per session id, never a directory overwrite.

🔧 Development

pnpm install
pnpm run typecheck
pnpm test

🗂️ Package layout

src/index.ts     Pi package entrypoint
src/migrate.ts   Command parsing, claim logic, and migration flow
src/storage.ts   Storage adapter: path encoding, dangling scan, atomic header rewrite
src/config.ts    Configuration loading and persistence
src/settings.ts  Interactive settings UI
test/            Deterministic unit and integration tests

🔎 Keywords

Pi extension, Pi coding agent, session migration, project relocation, dangling sessions, session backup, TypeScript Pi package.

📄 License

MIT. See LICENSE.