zot24 Pi — extend and improve the coding harness
Pi is the minimal terminal coding harness at pi.dev (@earendil-works/pi-coding-agent). This skill is the procedure for changing it.
Procedure
- Classify the job. Match one row in the package table: extend loop / custom provider / extension / skill / theme / pi package / CLI-TUI / fork / debug / from-source / evals / telemetry / remote protocol. Done when one row matches.
- Open a local clone of
https://github.com/earendil-works/pi(canonical;pi-mono301s here). Clone outsideskills/pi/. Done whenpackages/is present in that clone. - Read the matching
docs/file. Open the file named in the table and read the section that covers this job. Forextensions.md, use its Table of Contents and grep to the section. Size warning:extensions.md(162 KB),69 KB),rpc.md(sdk.md(48 KB),44 KB). When the table says not cached, open that clone README / package path instead. Done when the named section is in context, or — if the cell says not cached — the clone README / package path is in context.tui.md( - Change the package path in the clone. Edit that clone. Done when the edit is under that package path.
- From-source checks (after a code change):
npm install --ignore-scripts(README;docs/development.mdomits the flag — follow README).npm run checkafter any code change, full output (docs/agents-upstream.md/ AGENTS.md:31). Fix every error, warning, and info.- Tests:
./test.shfrom repo root for non-e2e; a specific test from the package root otherwise. Run the full vitest suite only through those wrappers. - Run
npm run buildornpm testonly when the user asks (docs/agents-upstream.md/ AGENTS.md:32)../pi-test.shruns Pi from source without a full build. - Debug a TUI/render bug:
/debug→~/.pi/agent/pi-debug.log. docs/development.mdoffersnpm testand plainnpm install;docs/agents-upstream.mdoverrides it.- Done when
npm run checkis clean and the touched package's test passes (or the debug log exists for a TUI/render bug).
- Contributing. Read
docs/contributing.mdbefore opening an upstream PR. New-contributor PRs auto-close until a maintainer postslgtm. Done when that file is in context.
Fork/rebrand: read docs/development.md section Forking / Rebranding. Platform setup (Windows / Termux / tmux / terminal / aliases) lives on the live site — open https://pi.dev/docs/latest/<slug> only when that is the job.
Package table
docs/development.md lists a four-package tree. Live packages/ has ten directories. This table wins.
| Job | Open path | Doc (read the named section) |
|---|---|---|
| agent loop | packages/agent |
package-agent.md, sdk.md (large) |
| custom provider | packages/ai + packages/coding-agent/examples/extensions/custom-provider-* |
custom-provider.md, package-ai.md |
| extension | packages/coding-agent + packages/coding-agent/examples/extensions/ |
extensions.md (large — ToC + grep) |
| skill | packages/coding-agent |
skills.md |
| theme | packages/tui + packages/coding-agent |
themes.md, tui.md (large) |
| pi package | packages/coding-agent |
packages.md |
| CLI / TUI | packages/coding-agent + packages/tui |
usage.md, tui.md (large) |
| fork / rebrand | packages/coding-agent (package.json) |
development.md Forking / Rebranding |
| from-source | clone root | agents-upstream.md, development.md |
| debug | clone; log at ~/.pi/agent/pi-debug.log |
development.md section Debug Command (/debug → ~/.pi/agent/pi-debug.log) |
| remote protocol | packages/protocol, packages/client, packages/server (experimental) |
not cached; read packages/protocol/README.md, packages/client/README.md, packages/server/README.md in the clone (rpc.md / sdk.md are JSONL RPC / SDK, not this CBOR protocol) |
| evals | packages/evals (private) |
not cached; read packages/evals/ in the clone |
| telemetry | packages/telemetry |
readme-upstream.md All Packages row + settings.md |
| sqlite sessions | packages/session-backends/sqlite-node |
package-agent.md section SQLite session backends |
Documentation
- Quickstart · Usage · Settings · Keybindings
- Providers · llama.cpp · Models · Custom provider
- Extensions (large) · Skills · Themes · Packages · Prompt templates
- Sessions · Session format · Compaction
- SDK (large) · RPC (large) · JSON · TUI (large)
- Development · AGENTS.md · Contributing
- Security · Containerization · Environment variables
- README · package-agent · package-ai · package-tui
Coding-agent's GitHub README overlaps usage.md; open the clone README only when that overlap is the question.
Upstream
- Docs: https://pi.dev/docs/latest
- Repo: https://github.com/earendil-works/pi
- Slack/chat: https://github.com/earendil-works/pi-chat — open only when the job is chat
Sync
Run .github/workflows/scripts/sync-skill.sh skills/pi to refresh docs/. Compare with .github/workflows/scripts/sync-skill.sh skills/pi --dry-run.