pi-park

pi-park lets a Pi agent safely wrap up a long-running task, save a durable project-local handoff, and resume it after the terminal, machine, or agent session has been restarted.

Install

Install the package from npm:

pi install npm:@toddzheng024/pi-park

Then restart Pi or run /reload.

To install directly from a local checkout instead:

pi install /absolute/path/to/pi-park

For local development, load it for one run:

npm install
npm run check
pi -e .

The extension targets compatible @earendil-works/pi-coding-agent 0.83.x releases.

Park work

Run this from the Pi session that is doing the long task:

/park

An optional note can tell the agent what must happen before it stops:

/park finish the current migration step and record the failed command

When the agent is busy, the request is delivered as a steer after its current tool calls finish. The agent is instructed to:

1. stop expanding the task;
2. leave the smallest in-flight operation in a safe state;
3. run only the checks needed to record the real state;
4. call save_park exactly once; and
5. stop after reporting the saved path.

/park does not kill an in-flight tool and does not automatically shut Pi down. Once save_park reports a path, the handoff is on disk and it is safe to close the session or reboot.

Only one save_park call can succeed for each /park request. If the agent settles without saving, the pending request is cleared and Pi tells you to retry. Blank core fields and empty progress or left-to-do lists are rejected rather than producing an incomplete handoff.

Resume or obsolete work

Start Pi in the same project and run:

/get-parks

The command lists active parks for the current project, newest first. Select one and then choose:

• Resume this park — injects the complete handoff into a new agent turn. The continuation prompt requires the agent to verify the current worktree, branch, tests, and external state before trusting the recorded state.
• Mark obsolete — asks for confirmation, changes the park status to obsolete, and hides it from future lists. The Markdown file is preserved.

Resume requires the agent to be idle so a parked task cannot be mixed into another in-flight task.

Storage format

Each park is an individual Markdown file under:

<project-root>/.pi/park/<utc-timestamp>-<title>-<nonce>.md

The YAML frontmatter records the schema version, lifecycle status, title, exact project path, git branch, and timestamps. The Markdown body always contains:

• Background
• Task
• Progress
• Left To Do
• Decisions
• Relevant Files
• Verification
• Notes

For Git worktrees, the project root comes from git rev-parse --show-toplevel; non-Git projects use Pi's working directory. Project path and branch are captured by the extension at save time rather than supplied by the model. Park creation uses a non-overwriting write, and obsolete transitions use an atomic same-directory rename.

The storage layer refuses symlinked .pi or .pi/park directories, ignores handoffs whose recorded project path does not match the current project, and caps handoffs at 256 KiB before injecting them into agent context.

Development

npm run typecheck
npm test
npm run check