pi-pie

@furbyhaxx/pi-pie provides pie, a TypeScript wrapper for running pi with named config environments, plus a small pi extension that injects active environment/session metadata into the system prompt.

Yes, it is a wrapper for a tool named pi called pie. Naming things remains a solved problem, obviously.

Features

• Preserves the old shell-wrapper behavior:
  • pie uses the cwd's remembered environment when one exists.
  • pie <env> [pi args...] runs pi with PI_CODING_AGENT_DIR set to <root>/environments/<env>.
  • pie -l / pie --list lists environments.
• Stores the remembered environment in pi's shared session directory:
  • <root>/sessions/<sanitized-cwd>/environment
  • not in ./.pi/environment anymore.
• Migrates legacy ./.pi/environment on first read without deleting it.
• Keeps auth.json and sessions/ shared across environments via safe symlinks.
• Injects the package extension with pi -e <package>/extensions/pie.ts for normal wrapped pi sessions.
• Adds /env inside pi for status/list/create/clone/path/doctor/repair/migrate.

Install

Global CLI from npm

After the package is published, install the persistent pie command globally:

npm install -g @furbyhaxx/pi-pie
# or, because typing fewer characters is apparently still legal:
npm i -g @furbyhaxx/pi-pie

Then run:

pie --help
pie env list
pie auto

One-off with npx

Use npx when you want to run the published CLI without a global install:

npx @furbyhaxx/pi-pie --help
npx @furbyhaxx/pi-pie env list
npx @furbyhaxx/pi-pie auto -p "hello"

From the GitHub repo

Install directly from git:

npm install -g git+https://github.com/furbyhaxx/pi-pie.git
# or
npm install -g github:furbyhaxx/pi-pie

Or clone and install the local checkout:

git clone https://github.com/furbyhaxx/pi-pie
cd pi-pie
npm install
npm install -g .

Not via pi install

pi-pie is primarily a binary package. Install it with npm install -g, run it with npx, or install it from the GitHub repo. Do not use:

pi install npm:@furbyhaxx/pi-pie

That would install pi package resources, not the pie binary, which is the whole point here. Tiny detail, wildly important.

The companion extension is injected automatically by the pie CLI with pi -e <package-root>/extensions/pie.ts.

Directory model

Default root:

${PI_PIE_ROOT:-${PI_CODING_AGENT_DIR:-~/.pi/agent}}

If PI_CODING_AGENT_DIR already points at <root>/environments/<env>, pie derives <root> from that path.

Environment layout:

<root>/
├── auth.json
├── sessions/
│   └── --sanitized-cwd--/
│       └── environment
└── environments/
    ├── .template/
    ├── auto/
    │   ├── auth.json -> <root>/auth.json
    │   └── sessions -> <root>/sessions
    └── default/

CLI usage

pie                    # use remembered env for cwd, else plain pi
pie auto               # run env `auto` and remember it for this cwd
pie auto -p "hello"    # forward pi args after env
pie -l                 # list environments
pie --no-pie-extension auto

Environment commands

pie env list
pie env current
pie env create <name>
pie env clone <src> <dst>
pie env path [name]
pie env doctor [name]
pie env repair [name]
pie env migrate

pie env clone <src> <dst> recursively copies the source environment directory into a new target environment. Regular files/directories are copied. Symlinks are recreated as symlinks. Managed auth.json and sessions links are recreated to point at the shared root.

There is intentionally no useful use command. Launch with pie <env> instead.

Pi extension

For normal wrapped sessions, pie launches:

pi -e <package-root>/extensions/pie.ts ...

The extension appends a system reminder. For wrapper-launched sessions it starts like this; package-only pi runs use neutral wording (This pi process is using a pie-managed environment.):

<system-reminder>
This pi process was launched through `pie`.

Environment:
- name: auto
- PI_CODING_AGENT_DIR: ~/.pi/agent/environments/auto
- shared root: ~/.pi/agent
- sticky env file: ~/.pi/agent/sessions/--cwd--/environment

Session:
- session id: ...
- session name: ...
- session file: ...
- cwd: ...

Use PI_CODING_AGENT_DIR for environment-local pi config. Auth and sessions are
shared through the pie root.
</system-reminder>

It also registers:

/env
/env status
/env list
/env create <name>
/env clone <src> <dst>
/env path [name]
/env doctor [name]
/env repair [name]
/env migrate

Development

npm install
npm test
npm run build
npm pack --dry-run

Publishing checklist

npm test
npm run build
npm pack --dry-run
npm publish --access public

The package already declares:

{
  "publishConfig": { "access": "public" }
}

Safety behavior

pie refuses to overwrite real files or directories at:

• <env>/auth.json
• <env>/sessions

Wrong symlinks are replaced. Missing symlinks are created. Real files/directories require manual cleanup, because clobbering config is for amateurs and malware.

License

MIT