pi-coding-agent

Files (46)

• SKILL.md
• metadata.json
• INDEX.md · references/
• configuration.md · references/core/
• resources.md · references/core/
• sessions.md · references/core/
• usage.md · references/core/
• development.md · references/development/
• extensions.md · references/development/
• providers.md · references/development/
• tui.md · references/development/
• json.md · references/integration/
• rpc.md · references/integration/
• sdk.md · references/integration/
• README.md · references/platform/
• containerization.md · references/safety/
• security.md · references/safety/
• compaction.md · references/upstream/
• containerization.md · references/upstream/
• custom-provider.md · references/upstream/
• development.md · references/upstream/
• docs.json · references/upstream/
• extensions.md · references/upstream/
• index.md · references/upstream/
• json.md · references/upstream/
• keybindings.md · references/upstream/
• models.md · references/upstream/
• packages.md · references/upstream/
• prompt-templates.md · references/upstream/
• providers.md · references/upstream/
• quickstart.md · references/upstream/
• rpc.md · references/upstream/
• sdk.md · references/upstream/
• security.md · references/upstream/
• session-format.md · references/upstream/
• sessions.md · references/upstream/
• settings.md · references/upstream/
• shell-aliases.md · references/upstream/
• skills.md · references/upstream/
• terminal-setup.md · references/upstream/
• termux.md · references/upstream/
• themes.md · references/upstream/
• tmux.md · references/upstream/
• tui.md · references/upstream/
• usage.md · references/upstream/
• windows.md · references/upstream/

SKILL.md (first lines)

# Pi coding-agent

## Purpose

Use this skill as a routing layer for Pi coding-agent tasks. Do not load every reference at once. Start with the smallest matching guide in `references/INDEX.md`, then read an upstream snapshot only when an exact option, event, type, or protocol detail is required.

## Operating workflow

1. **Classify the request**: daily CLI use, configuration, resources, sessions, automation, extension development, UI development, security, or platform setup.
2. **Read one focused reference** from `references/` before making version-sensitive claims.
3. **Inspect only the environment needed for the action**: check `pwd`, `pi --version`, `pi --help`, project `AGENTS.md`, or related files when they can change the result. Do not run an environment checklist for explanation-only or narrowly scoped tasks.
4. **Choose the smallest interface**: use the CLI for normal work, JSON for an event stream, RPC for a process/client boundary, and the SDK for in-process Node.js integration.
5. **Act with explicit scope**: make cwd, provider/model, session behavior, and project trust explicit only when they affect correctness or safety.
6. **Verify the behavior changed or configured by the task** and report failures without exposing credentials. Broaden verification only when the change or new evidence justifies it.

## Fast task router

| User intent | Read first |
|---|---|
| Install, authenticate, start Pi, use files, shell commands, slash commands, or CLI flags | `references/core/usage.md` |
| Configure API keys, providers, models, settings, thinking, retries, or keybindings | `references/core/configuration.md` |
| Create or use Skills, prompt templates, or Pi packages | `references/core/resources.md` |
| Resume, fork, clone, navigate, inspect, or compact sessions | `references/core/sessions.md` |
| Consume structured events from a one-shot run | `references/integration/json.md` |
| Build a language-agnostic or subprocess client | `references/integration/rpc.md` |
| Embed Pi in a Node.js application | `references/integration/sdk.md` |
| Add tools, commands, hooks, or lifecycle behavior | `references/development/extensions.md` |
| Add a model/provider, proxy, OAuth, or custom stream | `references/development/providers.md` |
| Build custom TUI, themes, or keybindings | `references/development/tui.md` |
| Run untrusted or unattended work | `references/safety/security.md`, then `containerization.md` |
| Fix terminal, tmux, Windows, Termux, or shell behavior | `references/platform/README.md` |

## Essential facts

- The normal built-in tools are `read`, `bash`, `edit`, and `write`; `grep`, `find`, and `ls` are also available through tool options.
- Interactive mode is `pi`; one-shot mode is `pi -p`; JSON events use `pi --mode json`; JSONL client integration uses `pi --mode rpc`.
- `@path` includes a file in the prompt. In interactive mode, `!command` runs bash and sends its output to the model; `!!command` runs it without adding the output to model context.
- Context files include global `~/.pi/agent/AGENTS.md` and project/ancestor `AGENTS.md` or `CLAUDE.md`. `/reload` reloads resources and context files.
- Sessions persist under `~/.pi/agent/sessions/` by default. Use `/resume`, `/new`, `/tree`, `/fork`, `/clone`, and `/compact`, or their CLI equivalents.
- Project Trust controls loading of project-local Pi resources; it is **not** a sandbox. Pi runs with the permissions of the launching user and has no built-in sandbox.
- Skills, extensions, packages, model configuration, and project-local resources can execute or instruct arbitrary actions. Review them before enabling them.

## Safety rules

- Never print, paste, or commit API keys, OAuth tokens, `auth.json`, or secret environment values.
- Do not treat a trusted project, a skill, or a package as safe merely because Pi loaded it.
- For untrusted repositories, generated code that will run unattended, or destructive automation, recommend a container, VM, micro-VM, or policy-controlled sandbox and mount only required paths or credentials.
- Do not invent a Pi API or configuration field. Read the focused reference or the matching file in `references/upstream/`.
- Do not use RPC built-in TUI commands as if they were protocol commands; RPC clients must consume JSONL responses/events and handle `streamingBehavior` while a run is active.
- Do not load `references/upstream/` wholesale. It is a version-pinned fallback reference, not default context.

## Completion

Before claiming completion, verify the parts of Pi behavior the request actually changed or depends on. For extension or SDK work, run the relevant TypeScript/tests and read the exact upstream reference for the API being used. Do not require unrelated provider, session, trust, or interface checks for a task that does not touch them.

From minfengyuan/harness-knowledge-base, MIT.

More from minfengyuan/harness-knowledge-base