pi-agent-stack-zilchfp

Public-safe base Pi agent stack for keeping Pi consistent across devboxes.

Default mode is global. It writes:

~/.pi/agent/settings.json

Use project mode only when a specific repo needs its own .pi/settings.json override.

Quick start

After package is published to npm:

npm install -g --ignore-scripts @zilchfp/[email protected] && pi-stack-bootstrap --install

Then authenticate Copilot once per devbox:

pi
/login -> GitHub Copilot

Done. Now pi in any repo uses the pinned global stack.

One-shot without installing stack CLI globally

After publish, this also works:

npx -y @zilchfp/[email protected] --install

This bootstraps global Pi settings, but does not leave pi-stack-check / piz commands installed globally. Prefer the Quick start command for normal devboxes.

What bootstrap does

pi-stack-bootstrap --install:

1. writes ~/.pi/agent/settings.json,
2. pins the stack package: npm:@zilchfp/[email protected],
3. pins extra public Pi packages from stack/packages.json,
4. installs missing helper binaries fd and ripgrep so Pi does not try GitHub downloads on first startup,
5. installs rtk via Cargo when Cargo is available, so pi-rtk-optimizer can rewrite commands,
6. installs/upgrades Pi CLI to stack/versions.json,
7. runs pi update --extensions,
8. keeps Copilot auth local; no token copied.

Skip helper binary install if you want to manage tools yourself:

pi-stack-bootstrap --install --skip-tools

Skip only rtk:

pi-stack-bootstrap --install --skip-rtk

Daily commands

Check global Pi stack:

pi-stack-check

Install/check helper binaries separately:

pi-stack-ensure-tools

Start Pi with gate:

piz

Update global settings after a new stack release:

pi-stack-bootstrap --stack-package npm:@zilchfp/[email protected] --install

Optional project mode

Only use this when a repo should commit its own Pi config:

pi-stack-bootstrap --project Q:/path/to/repo --install

Project mode writes:

<repo>/.pi/settings.json
<repo>/.gitignore

Project settings override global settings when Pi runs inside that repo.

Before npm publish

If the npm package is not published yet, install from git source instead:

npm install -g --ignore-scripts git+ssh://[email protected]/zilchfp/pi-agent-stack-zilchfp.git#<commit-or-tag> && pi-stack-bootstrap --stack-package git:[email protected]:zilchfp/pi-agent-stack-zilchfp.git@<commit-or-tag> --install

Use HTTPS instead of SSH if preferred:

npm install -g --ignore-scripts git+https://github.com/zilchfp/pi-agent-stack-zilchfp.git#<commit-or-tag> && pi-stack-bootstrap --stack-package https://github.com/zilchfp/pi-agent-stack-zilchfp@<commit-or-tag> --install

Public base vs private overlay

This package is public-safe. Do not put business-private prompts, URLs, MCP config, model config, or internal extensions here.

Private/business behavior belongs in a separate private overlay package, e.g. target/global settings can include:

{
  "packages": [
    "npm:@zilchfp/[email protected]",
    "npm:@org/[email protected]"
  ]
}

Included extensions

See docs/extensions.md.

Publish notes

First publish may require npm 2FA:

npm run check
npm pack --dry-run
npm publish --access public --otp <6-digit-code>

After first publish, configure npm Trusted Publisher:

Provider: GitHub Actions
Organization/user: zilchfp
Repository: pi-agent-stack-zilchfp
Workflow filename: publish.yml
Allowed actions: npm publish

Then release by tag:

npm version patch
git push origin main --tags

Security

Pi packages/extensions run with full system permissions. Review source before bumping packages.

Secrets never belong in this package or .pi/settings.json: API keys, OAuth/session tokens, cookies, GitHub/npm tokens, SSH private keys, cloud credentials, kubeconfig, database URLs, webhook secrets.