| name | pi-coding-agent |
| description | Use and investigate the Pi coding agent CLI. Covers interactive, print, JSON, and RPC modes; model and tool flags; sessions; local OpenAI-compatible models; skills; extensions; and the pi monorepo. Use when running `pi`, automating it, configuring models.json, writing Pi extensions or skills, or answering how Pi implements a behavior. |
Pi Coding Agent
Use this skill to operate Pi or trace its behavior from documentation and source.
Evidence order
Pi changes quickly, so establish the relevant version before relying on a flag,
schema, or source path:
- Run
command -v pi and pi --version for the installed CLI.
- Run
pi --help for version-current flags and environment variables. If Pi
tries to initialize writable state in a restricted environment, retry with an
isolated PI_CODING_AGENT_DIR under a temporary directory.
- Locate a source checkout from the current workspace or ask the user for its
path. Do not assume a machine-specific clone location.
- Compare the checkout's
packages/coding-agent/package.json version with the
installed version before treating its docs or source as matching runtime
behavior.
- Use the canonical docs at
https://pi.dev/docs/latest when local sources are
absent or stale.
State which source supports the answer and call out version mismatches.
See references/navigation.md for the documentation
and monorepo map.
Safe operating rules
- Treat Pi prompts, tool access, commits, pushes, and external writes as separate
authority. A request to explain Pi does not authorize running an agent that can
edit the user's checkout.
- For inspection, prefer
--tools read,grep,find,ls and --no-session.
- Never print or copy
auth.json, API keys, or provider credentials.
- Inspect
models.json structurally with redaction; do not expose apiKey,
headers, or command-backed secrets.
- Verify local model endpoints before launching a long agent run.
- Do not mutate Pi settings, install packages, or remove resources unless the
user requested that change.
Common commands
pi
pi "Summarize this repository"
pi @README.md @src/app.ts "Review"
pi --no-session -p "List TypeScript files"
pi --tools read,grep,find,ls --no-session -p "Review this code"
pi -c
pi -r
Use --provider and --model when reproducibility matters:
pi --provider <provider> --model <model-id> --no-session -p "<prompt>"
Read references/cli.md before composing less common
invocations.
Local and custom models
Pi reads custom providers from ${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/models.json.
Do not assume that a configured model ID matches what a local server currently
serves. Query the server's model endpoint, compare it with the redacted config,
then run a minimal --no-session -p smoke test.
Use references/local-models.md for schemas, local
server examples, secret handling, and verification.
Programmatic use
- Plain
-p: one-shot answer for shell scripts.
--mode json: JSONL event stream for observing a one-shot run.--mode rpc: bidirectional JSONL for controlling a long-lived subprocess.- SDK: in-process TypeScript integration.
Use the smallest surface that meets the request. See
references/programmatic.md for event handling and
client patterns.
Extensions and skills
Use a Pi skill for reusable instructions and bundled resources. Use a TypeScript
extension when the behavior needs tools, commands, flags, lifecycle hooks, UI, or
provider integration.
Read references/extensions.md, then verify the
current API against the matching installed docs or source before writing code.
Completion
Report:
- the installed Pi version and source/docs version used;
- the exact command, config path, or source files inspected;
- whether the operation was read-only or mutated Pi/user state;
- validation performed; and
- any version mismatch, unavailable endpoint, or unverified assumption.
