Pi normally lives in the directory where you started it. Teleport lets the agent move the running session to another directory, another repository, or a fresh Git worktree — and jump back when the job is done. The conversation continues and the session stays the same.

✦ Agent teleport
  /root/dev/pi/pi-worktrunk                ← from (blue)
  └─→ /root/dev/pi/pi-agent-teleport       ← to (orange)

The agent keeps working after the move. You see one compact route row, not a new user message.

Install

pi install npm:pi-agent-teleport

Use it

Ask the agent to move or isolate the work:

Move this session to /root/dev/my-other-repo and continue there.

Create an isolated worktree for the login fix, move into it, and continue the task.

Go back to the previous repository and remove the worktree you created.

The agent calls Teleport itself. You do not need to remember a slash command or tool syntax. Teleport requires a persisted Pi session.

What it gives the agent

Teleport exposes a single teleport tool. There are no user-facing slash commands.

| Action | Purpose | |-----------|---------| | jump | Move the session to an existing directory. | | back | Move the session to the previous location. | | history | List completed moves. | | create | Create a linked Git worktree owned by Teleport. | | remove | Remove a clean worktree recorded as Teleport-owned. |

Typical flow:

create worktree → jump into it → do the work → back → remove the worktree

How a move works

1. Teleport writes a prepared transition to durable state.
2. It builds the destination session: same session id, updated cwd, full conversation.
3. It switches Pi to the destination session.
4. Only then it removes the source session file.
5. A hidden continuation starts the next agent turn inside the destination context.

If step 3 is cancelled or fails, Teleport removes the prepared destination and keeps the source untouched.

Inside Herdr, Teleport opens Git checkouts through herdr worktree open. They appear as workspaces grouped with their parent repository in the sidebar. It reuses the idle shell created by create, or makes a separate tab when a workspace already has other work. Plain directories still use a new tab in the current workspace. The destination tab uses the Pi session name, without a prefix. If the session has no name, it uses the destination folder name.

Teleport starts Pi with the destination session without stealing focus, confirms the process, and saves the destination workspace, tab, and pane IDs. The destination waits for that handoff to commit before continuing the task. Only then does Teleport close the source pane and clean up its session file. Other panels and tabs stay open. If the source pane is the last one in its workspace, Teleport first creates a shell tab in the original folder with --no-focus, so the workspace stays open. If confirmation fails, it closes only the destination it prepared and keeps the source.

Managed worktrees

Outside Herdr, create records ownership before running Git. Inside Herdr, it uses herdr worktree create and records the returned checkout path and workspace IDs. Herdr chooses its configured checkout directory unless you supply path. Creating from a linked checkout still uses that checkout’s commit as the default base.

remove requires all of these:

• a matching Teleport ownership record,
• a matching Git common directory,
• a clean worktree.

For a Herdr-created checkout, removal also requires the owning Herdr connection and a workspace containing only its idle shell. A workspace closed by back is reopened without focus before removal. Extra panes or running commands block removal; Teleport never kills neighboring work. Herdr removes the workspace together with the checkout.

Teleport never deletes an unrecorded resource, and it has no force option. After removing the worktree, Teleport asks Git to delete the branch with git branch -d. Git deletes a safely merged branch and refuses to delete an unmerged one.

Create results show the path, branch, and resourceId needed for remove. The history result lists managed worktrees with their IDs, so you can recover an ID after moving. remove requires that ID and still checks ownership and cleanliness.

State and recovery

State lives in $PI_CODING_AGENT_DIR/teleport/<session-id>/state.json. It holds a version, the active session, movement history, owned resources, and any in-flight transition.

On session start Teleport reconciles that state:

• a prepared transition keeps the source, even when the destination file already exists;
• a confirmed destination becomes the active session;
• transitions are cleared, and a missing active session or resource is dropped.

Requirements

• Pi 0.80 or newer.
• Node.js 22 or newer.
• Herdr integration needs HERDR_ENV=1, HERDR_PANE_ID, HERDR_TAB_ID, and HERDR_WORKSPACE_ID, plus the public herdr CLI with worktree commands. Teleport verifies the live caller IDs before changing Herdr state. Missing environment values use normal Git creation and in-process session switching. A valid but unreachable Herdr connection fails explicitly rather than silently switching modes.

Limitations

• Teleport cannot carry in-memory extension state. Extensions must restore state from Pi session entries or from disk.
• Pi exposes session replacement only to command contexts, so jump and back use a private one-shot command as transport. Teleport dispatches it after agent_settled, not while a prompt is running. It is plumbing, not a supported user API.
• Dirty managed worktrees must be cleaned manually before removal.
• A worktree is checkout isolation, not a security sandbox.

Development

npm test            # unit tests
npm run typecheck   # TypeScript check
npm run test:integration  # real Pi process test

License

MIT