pi-kit

Automated onboarding for Pi Coding Agent. Installs and configures packages interactively.

npx pi-kit

Works on macOS, Linux, and Windows.

---

What it does

Walks you through 13 steps:

1. Preflight checks (Node, Pi, Docker, existing provider keys)
2. Execution mode (local or Docker container)
3. Model providers (Pi /login guidance, optional custom models.json)
4. Reliability & editing safety
5. Human-in-the-loop controls
6. Parallel sub-agents
7. Persistent memory
8. Agent persona (Soul)
9. Web search & fetch
10. Proactivity & scheduling
11. Sandboxing & permissions
12. Integrations (Telegram, MCP…)
13. AGENTS.md behavior config

Every step is optional. You can skip anything.

Provider API keys should be stored with Pi's own /login flow when possible. pi-kit does not collect built-in provider keys. For custom OpenAI-compatible endpoints, it creates ~/.pi/agent/models.json when missing or adds a provider only when that provider id is not already present.

---

Adding or removing a package

One file to edit: src/registry.ts

Add one object to the array:

{
  id: 'my-package',           // unique key
  npm: 'author/my-pi-package', // passed to `pi install npm:...`
  group: 'reliability',        // which step it appears in
  label: 'My Package',
  description: 'What it does in one line',
  optional: true,              // ask the user, or always install
  enabled: true,
  conflicts: ['other-package'], // optional: cannot be installed together
}

To remove: delete the object, or set enabled: false.

That's it. No step code changes needed.

---

Adding a new step

1. Add packages with a new group name to src/registry.ts
2. Add one entry to src/flows/index.ts:

{
  group: 'my-group',
  title: 'My new step',
  description: 'What this group of packages does',
}

The step appears automatically in order. No other files change.

---

Per-package configuration

Packages can define a configure function that runs after install:

{
  id: 'my-package',
  npm: 'my-pi-package',
  group: 'web',
  label: 'My Package',
  description: '...',
  optional: true,
  configure: async ({ prompt, config, env }) => {
    const key = await prompt.password('API key')
    await env.set('MY_API_KEY', key)
    config.set('my-package.key', key)
  },
  postInstall: ({ ui }) => {
    ui.hint('Configure further in ~/.pi/agent/my-package.json')
  },
}

Available in configure and postInstall:

Parameter	Type	Description
prompt	object	confirm, select, input, password
config	object	In-memory store, flushed to pi-kit/config.json
env	object	Shell profile / .env writer
fs	object	File writers (souls, schedules, AGENTS.md)
paths	object	Platform-correct config paths
ui	object	Terminal output helpers

---

Platform notes

Platform	Env vars	Container
macOS	~/.zshrc or ~/.bash_profile	Docker or Apple container
Linux	~/.bashrc or ~/.profile	Docker
Windows	.pi/agent/.env	Docker (WSL)

---

Plugin support (roadmap)

Future: external package registries via pi-kit.config.js in the project root:

// pi-kit.config.js
export default {
  packages: [
    {
      id: 'my-org-package',
      npm: '@my-org/pi-extension',
      group: 'integrations',
      label: 'My Org Extension',
      description: 'Internal tooling',
      optional: true,
    }
  ]
}

---

Contributing

See the org-wide CONTRIBUTING.md.

---

License

Apache-2.0 — see LICENSE.