@counterposition/skill-pi 0.65.2 → 0.73.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +26 -9
  2. package/package.json +1 -1
  3. package/skills/pi/README.md +8 -14
  4. package/skills/pi/SKILL.md +34 -166
  5. package/skills/pi/references/extensions.md +40 -20
  6. package/skills/pi/references/packages.md +7 -3
  7. package/skills/pi/references/providers.md +57 -8
  8. package/skills/pi/references/sdk.md +16 -8
  9. package/skills/pi/references/settings.md +77 -4
package/README.md CHANGED
@@ -1,25 +1,42 @@
1
- # Skill Pi Package
1
+ # Pi Skill
2
2
 
3
- Single-skill npm package for installing the `pi` skill with `pi install`.
3
+ Pi's own system prompt already points it at its source documentation. But when you use a different coding agent — Claude Code, OpenCode, Codex CLI, or an IDE agent like Cursor or Windsurf — to work on Pi extensions, skills, packages, or configuration, that agent has no built-in knowledge of Pi's architecture. It will hallucinate APIs, invent settings, and confidently describe extension hooks that don't exist.
4
4
 
5
- Package versions track the Pi coding agent release that the bundled skill
6
- documentation targets.
5
+ This skill gives any coding agent grounded knowledge of Pi via the [Agent Skills](https://agentskills.io/home) standard. It injects task-specific reference documentation into context so the agent reasons from facts — about extensions, settings, providers, sessions, and the SDK — rather than from plausible fictions.
7
6
 
8
7
  ## Install
9
8
 
10
9
  ```bash
10
+ # as a skill
11
+ npx skills add counterposition/pi --skill pi
12
+
13
+ # as a Pi package
11
14
  pi install npm:@counterposition/skill-pi
12
15
  ```
13
16
 
14
- Maintainer smoke test from the monorepo root:
17
+ ### Maintainer Paths
15
18
 
16
19
  ```bash
20
+ # from a local checkout
21
+ npx skills add /absolute/path/to/pi --skill pi
22
+
23
+ # packaged install from monorepo root
17
24
  pi install ./packages/skill-pi
18
25
  ```
19
26
 
20
- ## Contents
27
+ If you develop inside this repo, Pi already loads the skill via `.pi/settings.json`.
28
+
29
+ ## What this covers
30
+
31
+ Pi's architecture and package layout. Skill authoring, discovery, and routing. Extensions, tools, and UI hooks. Settings, models, providers, and packages. Sessions, forks, and compaction. The SDK and RPC interface.
32
+
33
+ The reference material lives in `references/` as task-specific documents — not a single monolith, but pieces sized for injection into a conversation when relevant.
21
34
 
22
- - `skills/pi/` - packaged copy of the canonical Pi skill
23
- - `../../skills/pi` - canonical source used for GitHub-based `npx skills add`
35
+ ## Files
24
36
 
25
- The packaged skill is synced from the canonical source with `pnpm run sync:skills`.
37
+ | Path | Purpose |
38
+ | ------------------ | ------------------------------------- |
39
+ | `SKILL.md` | Trigger rules and routing description |
40
+ | `references/` | Task-specific Pi reference documents |
41
+ | `evals/evals.json` | Example evaluation cases |
42
+ | `LICENSE.md` | GPLv3 license text |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@counterposition/skill-pi",
3
- "version": "0.65.2",
3
+ "version": "0.73.0",
4
4
  "description": "Pi coding agent reference skill — extensions, settings, providers, SDK/RPC, packages, and .pi/ config",
5
5
  "keywords": [
6
6
  "ai-skill",
package/skills/pi/README.md CHANGED
@@ -1,14 +1,8 @@
1
1
  # Pi Skill
2
2
 
3
- > Knowing others is intelligence; knowing yourself is true wisdom.
4
- >
5
- > — Lao Tzu, *Tao Te Ching*
3
+ Pi's own system prompt already points it at its source documentation. But when you use a different coding agent — Claude Code, OpenCode, Codex CLI, or an IDE agent like Cursor or Windsurf — to work on Pi extensions, skills, packages, or configuration, that agent has no built-in knowledge of Pi's architecture. It will hallucinate APIs, invent settings, and confidently describe extension hooks that don't exist.
6
4
 
7
- A coding agent that cannot reason about its own architecture will invent APIs that don't exist, hallucinate configuration formats, and give confident wrong answers about its own internals. The failure mode is subtle: the answers *sound* right, because the agent knows how systems like it tend to work. But Pi is specific, and the details matter.
8
-
9
- This skill gives Pi self-knowledge. It injects task-specific reference documentation into context so that Pi reasons from grounded facts — about its extensions, settings, providers, sessions, and SDK — rather than from plausible fictions.
10
-
11
- Without this skill, Pi guesses about itself. With it, Pi *knows*.
5
+ This skill gives any coding agent grounded knowledge of Pi via the [Agent Skills](https://agentskills.io/home) standard. It injects task-specific reference documentation into context so the agent reasons from facts — about extensions, settings, providers, sessions, and the SDK — rather than from plausible fictions.
12
6
 
13
7
  ## Install
14
8
 
@@ -40,9 +34,9 @@ The reference material lives in `references/` as task-specific documents — not
40
34
 
41
35
  ## Files
42
36
 
43
- | Path | Purpose |
44
- |---|---|
45
- | `SKILL.md` | Trigger rules and routing description |
46
- | `references/` | Task-specific Pi reference documents |
47
- | `evals/evals.json` | Example evaluation cases |
48
- | `LICENSE.md` | GPLv3 license text |
37
+ | Path | Purpose |
38
+ | ------------------ | ------------------------------------- |
39
+ | `SKILL.md` | Trigger rules and routing description |
40
+ | `references/` | Task-specific Pi reference documents |
41
+ | `evals/evals.json` | Example evaluation cases |
42
+ | `LICENSE.md` | GPLv3 license text |
package/skills/pi/SKILL.md CHANGED
@@ -7,198 +7,66 @@ compatibility: "Pi-specific guidance for agents that support Agent Skills"
7
7
 
8
8
  # Pi Coding Agent
9
9
 
10
- Pi is a minimal terminal coding harness. It ships four default tools (`read`, `write`, `edit`, `bash`) and four execution modes (interactive TUI, print, JSON/RPC, SDK). Features like sub-agents, plan mode, permission flows, and MCP are intentionally left to extensions and Pi packages.
10
+ Pi is a minimal terminal coding harness. Default tools: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`. Modes: interactive (`pi`), print (`pi -p`), JSON (`--mode json`), RPC (`--mode rpc`), or embedded (`createAgentSession()`). Sub-agents, plan mode, permission flows, and MCP are intentionally left to extensions and Pi packages.
11
11
 
12
- Pi's philosophy: **adapt Pi to your workflows, not the other way around**. Users extend it via TypeScript extensions, skills, prompt templates, themes, and shareable Pi packages.
12
+ Pi's philosophy: **adapt Pi to your workflows, not the other way around**.
13
13
 
14
- ## Architecture at a Glance
14
+ ## Architecture
15
15
 
16
- The coding-agent stack centers on four core packages. The monorepo also includes adjacent packages such as `pi-web-ui`, `pi-mom`, and `pi-pods`.
16
+ Four core packages on npm (source: [github.com/badlogic/pi-mono](https://github.com/badlogic/pi-mono)):
17
17
 
18
- | Package | npm | Purpose |
19
- |---------|-----|---------|
20
- | `pi-ai` | `@mariozechner/pi-ai` | Unified LLM API across 20+ providers |
21
- | `pi-agent-core` | `@mariozechner/pi-agent-core` | Agent loop, tool execution, state management |
22
- | `pi-tui` | `@mariozechner/pi-tui` | Terminal UI component library |
23
- | `pi-coding-agent` | `@mariozechner/pi-coding-agent` | CLI, extensions, skills, sessions, settings |
24
-
25
- **Source:** [github.com/badlogic/pi-mono](https://github.com/badlogic/pi-mono)
18
+ | Package | Purpose |
19
+ |---------|---------|
20
+ | `@mariozechner/pi-ai` | Unified LLM API across 20+ providers |
21
+ | `@mariozechner/pi-agent-core` | Agent loop, tool execution, state |
22
+ | `@mariozechner/pi-tui` | Terminal UI components |
23
+ | `@mariozechner/pi-coding-agent` | CLI, extensions, skills, sessions, settings |
26
24
 
27
25
  ## File System Layout
28
26
 
29
27
  ```text
30
- ~/.pi/agent/ # Global config directory (PI_CODING_AGENT_DIR overrides)
28
+ ~/.pi/agent/ # Global config dir (PI_CODING_AGENT_DIR overrides)
31
29
  ├── settings.json # Global settings
32
30
  ├── auth.json # Credentials (0600 perms)
33
31
  ├── models.json # Custom provider/model definitions
34
32
  ├── keybindings.json # Keyboard shortcuts
35
- ├── presets.json # Named configurations (via preset extension)
36
- ├── extensions/ # Global extensions (auto-discovered)
37
- ├── skills/ # Global skills (auto-discovered)
38
- ├── prompts/ # Global prompt templates (auto-discovered)
33
+ ├── extensions/ # Auto-discovered
34
+ ├── skills/ # Auto-discovered
35
+ ├── prompts/ # Auto-discovered
39
36
  ├── themes/ # Custom themes
40
- ├── sessions/ # JSONL session files
41
- └── bin/ # Tool binaries (fd, ripgrep)
37
+ └── sessions/ # JSONL session files
42
38
 
43
39
  <project>/
44
- ├── .pi/ # Project-local config (overrides global)
45
- │ ├── settings.json # Project settings (merged over global)
46
- │ ├── extensions/ # Project extensions (auto-discovered)
47
- │ ├── skills/ # Project skills
48
- │ ├── prompts/ # Project prompt templates
49
- │ ├── themes/ # Project themes
50
- │ └── agents/ # Agent definitions (for subagent extension)
40
+ └── .pi/ # Project-local config (overrides global)
41
+ ├── settings.json
42
+ ├── extensions/
43
+ ├── skills/
44
+ ├── prompts/
45
+ ├── themes/
46
+ └── agents/ # Agent definitions (subagent extension)
51
47
  ```
52
48
 
53
49
  ## Key Concepts
54
50
 
55
- ### Extensions
56
-
57
- TypeScript modules that hook into Pi's lifecycle. They can register tools, intercept tool calls, add commands, build custom UIs, and persist state. Extensions have **full system access** — they run with the user's permissions.
58
-
59
- Read `references/extensions.md` for the complete API, lifecycle events, tool registration, UI methods, and working examples.
60
-
61
- ### Skills
62
-
63
- Markdown-based capability packages (`SKILL.md` with frontmatter). Pi loads skill names and descriptions into the system prompt; the full skill body is read on demand. Skills follow the Agent Skills standard.
64
-
65
- Read `references/skills.md` for the authoring guide, frontmatter schema, and directory conventions.
66
-
67
- ### Settings
68
-
69
- Hierarchical JSON configuration: project `.pi/settings.json` merges over global `~/.pi/agent/settings.json`. Controls model, thinking level, compaction, retry, shell, transport, and resource loading.
70
-
71
- Read `references/settings.md` for every setting with its type, default, and effect.
72
-
73
- ### Packages
74
-
75
- Bundles of extensions, skills, prompts, and themes distributed via npm, git, or local paths. Installed with `pi install`.
76
-
77
- Read `references/packages.md` for the package structure, `pi` manifest field, installation, and publishing.
78
-
79
- ### Context Files & Prompt Templates
80
-
81
- Pi loads `AGENTS.md` or `CLAUDE.md` from the global agent dir and from `cwd` up through parent directories. `.pi/SYSTEM.md` replaces the default system prompt, and `APPEND_SYSTEM.md` appends to it. Prompt templates in `prompts/` directories become slash commands.
82
-
83
- Read `references/settings.md` for discovery rules and config keys, and `references/packages.md` for how prompts/themes ship in packages.
84
-
85
- ### SDK
86
-
87
- Programmatic embedding via `createAgentSession()`. Gives full control over models, tools, extensions, sessions, and event streaming.
88
-
89
- Read `references/sdk.md` for factory options, event types, and usage patterns.
90
-
91
- ### Custom Providers & Models
92
-
93
- Add any OpenAI-compatible, Anthropic, Google, or custom LLM endpoint via `models.json` or extension-based `registerProvider()`.
94
-
95
- Read `references/providers.md` for provider configuration, auth methods, and the model schema.
96
-
97
- ### Common Patterns
98
-
99
- Practical recipes for permission gates, presets, sub-agents, git checkpoints, custom compaction, TUI components, and more.
100
-
101
- Read `references/patterns.md` for copy-paste-ready examples.
102
-
103
- ## Sessions & Compaction
104
-
105
- Sessions are append-only JSONL files with a tree structure (entries linked by `id`/`parentId`). This allows branching without modifying history. Key operations:
106
-
107
- - **`/tree`** — Navigate the session tree, jump to any point
108
- - **`Shift+T` in `/tree`** — Toggle timestamps on tree entry labels
109
- - **`/compact`** — Manually trigger context compaction
110
- - **`/fork`** — Branch from a specific point
111
- - **Auto-compaction** — Triggers when `contextTokens > contextWindow - reserveTokens`
112
-
113
- Compaction walks backward from the newest message, keeping `keepRecentTokens` (default 20,000) of recent conversation, and summarizes everything older. Extensions can intercept compaction via `session_before_compact`.
114
-
115
- ## Built-in Tools
116
-
117
- | Tool | Description |
118
- |------|-------------|
119
- | `read` | Read files (with offset/limit support, images, PDFs) |
120
- | `write` | Create or overwrite files |
121
- | `edit` | Line-based file editing with diffs |
122
- | `bash` | Execute shell commands with streaming output |
123
- | `grep` | Search file contents by pattern |
124
- | `find` | Find files by glob pattern |
125
- | `ls` | List directory contents |
126
-
127
- **Common tool sets:** `codingTools()` = `[read, bash, edit, write]`, `readOnlyTools()` = `[read, grep, find, ls]`. When you provide a custom `cwd` and explicit tools in the SDK, use `createCodingTools(cwd)` / `createReadOnlyTools(cwd)` so path resolution stays correct.
128
-
129
- ## Execution Modes
130
-
131
- | Mode | Start with | Use case |
132
- |------|-----------|----------|
133
- | Interactive | `pi` | Full TUI with editor, streaming, keybindings |
134
- | Print | `pi -p "prompt"` | Single-shot text output |
135
- | JSON | `pi --mode json "prompt"` | Newline-delimited event stream |
136
- | RPC | `pi --mode rpc` | JSON-RPC over stdin/stdout for IDE integration |
137
- | SDK | `createAgentSession()` | Embed in Node.js applications |
138
-
139
- ## Quick Reference: CLI Flags
140
-
141
- ```text
142
- pi [options] [@files...] [messages...]
143
-
144
- # package commands
145
- install <source> [-l]
146
- remove <source> [-l]
147
- uninstall <source> [-l]
148
- update [source]
149
- list
150
- config
151
-
152
- # modes and output
153
- -p, --print
154
- --mode json|rpc
155
- --export <in> [out]
156
-
157
- # model selection
158
- --provider <name>
159
- --model <pattern>
160
- --api-key <key>
161
- --thinking <level>
162
- --models <patterns>
163
- --list-models [search]
164
-
165
- # sessions
166
- -c, --continue
167
- -r, --resume
168
- --session <path|id>
169
- --fork <path|id>
170
- --session-dir <dir>
171
- --no-session
172
-
173
- # tools and resources
174
- --tools <list>
175
- --no-tools
176
- -e, --extension <source>
177
- --skill <path>
178
- --prompt-template <path>
179
- --theme <path>
180
- --no-extensions
181
- --no-skills
182
- --no-prompt-templates
183
- --no-themes
184
-
185
- # prompts and misc
186
- --system-prompt <text>
187
- --append-system-prompt <text>
188
- --verbose
189
- ```
51
+ - **Extensions** — TypeScript modules with full system access. Hook into Pi's lifecycle to register tools, intercept calls, add commands, build UI. → `references/extensions.md`
52
+ - **Skills** — Markdown capability packages (`SKILL.md` + frontmatter) following the Agent Skills standard. Pi loads names + descriptions into the system prompt; bodies load on demand. → `references/skills.md`
53
+ - **Settings** — Hierarchical JSON: project `.pi/settings.json` merges over global `~/.pi/agent/settings.json`. → `references/settings.md`
54
+ - **Packages** — Bundles of extensions/skills/prompts/themes via npm, git, or local paths. Installed with `pi install`. → `references/packages.md`
55
+ - **Context files & prompt templates** — Pi loads `AGENTS.md` / `CLAUDE.md` from the agent dir and from `cwd` up through ancestors. `.pi/SYSTEM.md` replaces the system prompt; `APPEND_SYSTEM.md` appends. Prompt templates in `prompts/` become slash commands. → `references/settings.md`
56
+ - **SDK** — Programmatic embedding via `createAgentSession()`; `createAgentSessionRuntime()` for session replacement. → `references/sdk.md`
57
+ - **Custom providers & models** — `models.json` or extension `pi.registerProvider()` for any OpenAI-/Anthropic-/Google-compatible or custom LLM endpoint. → `references/providers.md`
58
+ - **Sessions & compaction** — Append-only JSONL with a tree structure; branch with `/tree`, `/fork`, `/clone`, compact with `/compact`. Auto-compaction triggers when `contextTokens > contextWindow - reserveTokens`. Extensions intercept via `session_before_compact`. → `references/extensions.md` and `references/sdk.md`
190
59
 
191
60
  ## How to Use This Skill
192
61
 
193
- When working with Pi, read the appropriate reference file for the task at hand:
194
-
195
62
  | Task | Reference |
196
63
  |------|-----------|
197
64
  | Writing an extension (tools, commands, events, UI) | `references/extensions.md` |
198
- | Creating a skill (SKILL.md authoring) | `references/skills.md` |
199
- | Configuring Pi (settings.json options) | `references/settings.md` |
200
- | Context files, prompt templates, themes, and resource discovery | `references/settings.md` and `references/packages.md` |
65
+ | Creating a skill | `references/skills.md` |
66
+ | Configuring Pi (settings, env vars, CLI flags) | `references/settings.md` |
201
67
  | Building a shareable package | `references/packages.md` |
202
68
  | Embedding Pi programmatically | `references/sdk.md` |
203
69
  | Adding LLM providers or models | `references/providers.md` |
204
70
  | Looking for a recipe or pattern | `references/patterns.md` |
71
+
72
+ For exact CLI flags run `pi --help` or read the relevant reference. Resource flags (`--no-extensions`, `--no-skills`, `--no-context-files`, `--no-builtin-tools`, etc.) are documented in `references/settings.md`.
package/skills/pi/references/extensions.md CHANGED
@@ -18,13 +18,13 @@ Use `pi -e ./my-extension.ts` or `pi --extension ...` for quick tests. Put stabl
18
18
 
19
19
  ```typescript
20
20
  import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
21
- import { Type } from "@sinclair/typebox";
21
+ import { Type } from "typebox";
22
22
  import { StringEnum } from "@mariozechner/pi-ai";
23
23
  import { Text } from "@mariozechner/pi-tui";
24
24
  ```
25
25
 
26
- - Use `@sinclair/typebox` for schemas
27
- - Use `StringEnum` from `@mariozechner/pi-ai` for Google-compatible string enums
26
+ - Use `typebox` (1.x) for schemas. Legacy `@sinclair/typebox` is still aliased but `@sinclair/typebox/compiler` is not.
27
+ - Use `StringEnum` from `@mariozechner/pi-ai` for Google-compatible string enums.
28
28
 
29
29
  ## Quick Start
30
30
 
@@ -52,6 +52,9 @@ export default function (pi: ExtensionAPI) {
52
52
  },
53
53
  });
54
54
 
55
+ // For reusable tool definitions outside `pi.registerTool(...)`, use `defineTool({...})`
56
+ // — it preserves parameter type inference and can be passed via `customTools` to the SDK.
57
+
55
58
  pi.registerCommand("hello", {
56
59
  description: "Say hello",
57
60
  async handler(args, ctx) {
@@ -75,32 +78,24 @@ Useful session events:
75
78
  - `session_shutdown`
76
79
  - `resources_discover`
77
80
 
78
- Pi 0.65.0 removed the post-transition `session_switch` and `session_fork` events. Handle startup, reload, new, resume, and fork in `session_start` instead:
79
-
80
- ```typescript
81
- pi.on("session_start", async (event, ctx) => {
82
- if (event.reason === "fork" && event.previousSessionFile && ctx.hasUI) {
83
- ctx.ui.notify(`Forked from ${event.previousSessionFile}`, "info");
84
- }
85
- });
86
- ```
87
-
88
- Use `event.reason` to distinguish `"startup"`, `"reload"`, `"new"`, `"resume"`, and `"fork"`. For `"new"`, `"resume"`, and `"fork"`, `event.previousSessionFile` points at the session file being replaced.
81
+ `session_start` carries `event.reason` — `"startup" | "reload" | "new" | "resume" | "fork"` — and `event.previousSessionFile` for `"new"`/`"resume"`/`"fork"`. The old post-transition `session_switch` / `session_fork` events were removed; route all of those flows through `session_start`.
89
82
 
90
83
  Useful agent events:
91
84
 
92
85
  - `input`
93
- - `before_agent_start`
86
+ - `before_agent_start` — receives `event.systemPromptOptions` (a `BuildSystemPromptOptions`) so handlers can inspect the structured inputs feeding the system prompt
94
87
  - `agent_start`
95
88
  - `agent_end`
96
89
  - `turn_start`
97
90
  - `turn_end`
98
91
  - `message_start`
99
92
  - `message_update`
100
- - `message_end`
93
+ - `message_end` — return a replacement message to override usage/cost or rewrite the finalized assistant message
101
94
  - `context`
102
95
  - `before_provider_request`
96
+ - `after_provider_response` — inspect the provider HTTP status and headers before stream consumption
103
97
  - `model_select`
98
+ - `thinking_level_select` — observe interactive thinking-level changes
104
99
 
105
100
  Useful tool events:
106
101
 
@@ -110,6 +105,10 @@ Useful tool events:
110
105
  - `tool_result`
111
106
  - `tool_execution_end`
112
107
 
108
+ Tool results may include `terminate: true` to end the current tool batch without an automatic follow-up LLM turn — useful for tools that produce a structured final answer (see `examples/extensions/structured-output.ts` in the Pi repo).
109
+
110
+ `session_shutdown` events carry `event.reason` (`"quit" | "reload" | "new" | "resume" | "fork"`) and, where applicable, `event.targetSessionFile` so cleanup logic can distinguish teardown paths.
111
+
113
112
  ## Extension Context
114
113
 
115
114
  `ctx` gives extensions access to:
@@ -172,6 +171,8 @@ ctx.ui.notify("Done", "info");
172
171
 
173
172
  ctx.ui.setStatus("my-ext", "Processing...");
174
173
  ctx.ui.setWorkingMessage("Thinking deeply...");
174
+ ctx.ui.setWorkingIndicator({ frames: ["⣷", "⣯", "⣟", "⡿"], intervalMs: 80 });
175
+ ctx.ui.setWorkingVisible(false); // hide the built-in loader row
175
176
  ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"]);
176
177
  ctx.ui.setFooter((tui, theme) => new Text(theme.fg("dim", "Custom footer"), 0, 0));
177
178
  ctx.ui.setTitle("pi - custom");
@@ -179,16 +180,18 @@ ctx.ui.setTitle("pi - custom");
179
180
  ctx.ui.setEditorText("prefilled text");
180
181
  const current = ctx.ui.getEditorText();
181
182
  ctx.ui.pasteToEditor("extra text");
183
+ ctx.ui.setHiddenThinkingLabel("…");
184
+ const editorFactory = ctx.ui.getEditorComponent(); // wrap the active editor factory
182
185
 
183
186
  ctx.ui.setToolsExpanded(true);
184
187
 
188
+ ctx.ui.addAutocompleteProvider((query, ctx) => /* completions */); // stack on top of slash/path provider
189
+
185
190
  const result = await ctx.ui.custom((tui, theme, keybindings, done) => {
186
191
  return new Text("Press Enter", 0, 0);
187
192
  }, { overlay: true });
188
193
  ```
189
194
 
190
- Pi 0.64.0 also added `ctx.ui.setHiddenThinkingLabel(...)` so interactive extensions can customize the collapsed thinking label.
191
-
192
195
  ## Commands, Shortcuts, Flags
193
196
 
194
197
  ```typescript
@@ -233,15 +236,30 @@ pi.on("session_start", async (_event, ctx) => {
233
236
 
234
237
  ## Provider Integration
235
238
 
236
- Extensions can register providers:
239
+ Extensions can register or override providers:
237
240
 
238
241
  ```typescript
239
242
  pi.registerProvider("my-provider", {
243
+ name: "My Provider", // optional friendly label for /login
240
244
  baseUrl: "https://api.example.com",
241
245
  api: "openai-completions",
242
246
  apiKey: "MY_PROVIDER_KEY",
243
- models: [{ id: "my-model", name: "My Model", contextWindow: 128000, maxTokens: 4096 }],
247
+ models: [
248
+ {
249
+ id: "my-model",
250
+ name: "My Model",
251
+ contextWindow: 128000,
252
+ maxTokens: 4096,
253
+ baseUrl: "https://us-east.api.example.com", // per-model override
254
+ thinkingLevelMap: { off: null, minimal: "low", medium: "medium", high: "high", xhigh: "high" },
255
+ },
256
+ ],
244
257
  });
258
+
259
+ // Override-only: re-route an existing built-in provider through a proxy
260
+ pi.registerProvider("anthropic", { baseUrl: "https://proxy.example.com" });
261
+
262
+ pi.unregisterProvider("my-provider");
245
263
  ```
246
264
 
247
265
  If you need auth for a specific model request, use:
@@ -250,6 +268,8 @@ If you need auth for a specific model request, use:
250
268
  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
251
269
  ```
252
270
 
271
+ Pass `shouldStopAfterTurn` via the SDK to exit the agent loop gracefully after a completed turn. See `references/sdk.md` and `references/providers.md` for the full provider/model schema.
272
+
253
273
  ## Handy Patterns
254
274
 
255
275
  - Permission gates via `tool_call`
package/skills/pi/references/packages.md CHANGED
@@ -16,7 +16,10 @@ pi install ./relative/path/to/package
16
16
  pi remove npm:@foo/bar
17
17
  pi uninstall npm:@foo/bar
18
18
  pi list
19
- pi update
19
+ pi update # update pi itself + all installed packages (skips pinned)
20
+ pi update --self # update pi only
21
+ pi update --extensions # update packages only
22
+ pi update <source> # update one package
20
23
  pi config
21
24
  ```
22
25
 
@@ -92,8 +95,9 @@ If there is no `pi` manifest, Pi auto-discovers:
92
95
  - `@mariozechner/pi-agent-core`
93
96
  - `@mariozechner/pi-coding-agent`
94
97
  - `@mariozechner/pi-tui`
95
- - `@sinclair/typebox`
96
- - Other Pi packages must be bundled explicitly if your package depends on them
98
+ - `typebox` (legacy `@sinclair/typebox` still aliased)
99
+ - Other Pi packages must be bundled explicitly
100
+ - Git package installs run `npm install --omit=dev` — runtime needs go in `dependencies`, not `devDependencies`
97
101
 
98
102
  ## Package Filtering
99
103
 
package/skills/pi/references/providers.md CHANGED
@@ -4,15 +4,13 @@ Pi supports subscription-based providers via OAuth, API-key providers via env va
4
4
 
5
5
  ## Subscription Providers
6
6
 
7
- Use `/login` in interactive mode, then select a provider:
7
+ Use `/login` in interactive mode, then select a provider. The `/login` selector is fuzzy-searchable and shows where each entry's auth comes from (`--api-key`, env var, custom provider) without leaking the secret.
8
8
 
9
- - Anthropic Claude Pro / Max
9
+ - Anthropic Claude Pro / Max — third-party usage draws from extra usage and is billed per token (suppress the warning via `warnings.anthropicExtraUsage`)
10
10
  - OpenAI ChatGPT Plus / Pro (Codex)
11
11
  - GitHub Copilot
12
- - Google Gemini CLI
13
- - Google Antigravity
14
12
 
15
- Use `/logout` to clear stored OAuth credentials.
13
+ Use `/logout` to clear stored OAuth credentials. Pi 0.71.0 removed built-in Google Gemini CLI and Google Antigravity providers.
16
14
 
17
15
  ## API Key Providers
18
16
 
@@ -21,10 +19,13 @@ Use `/logout` to clear stored OAuth credentials.
21
19
  | Anthropic | `ANTHROPIC_API_KEY` | `anthropic` |
22
20
  | Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
23
21
  | OpenAI | `OPENAI_API_KEY` | `openai` |
22
+ | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
24
23
  | Google Gemini | `GEMINI_API_KEY` | `google` |
25
24
  | Mistral | `MISTRAL_API_KEY` | `mistral` |
26
25
  | Groq | `GROQ_API_KEY` | `groq` |
27
26
  | Cerebras | `CEREBRAS_API_KEY` | `cerebras` |
27
+ | Cloudflare AI Gateway | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_GATEWAY_ID`) | `cloudflare-ai-gateway` |
28
+ | Cloudflare Workers AI | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`) | `cloudflare-workers-ai` |
28
29
  | xAI | `XAI_API_KEY` | `xai` |
29
30
  | OpenRouter | `OPENROUTER_API_KEY` | `openrouter` |
30
31
  | Vercel AI Gateway | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway` |
@@ -32,9 +33,13 @@ Use `/logout` to clear stored OAuth credentials.
32
33
  | OpenCode Zen | `OPENCODE_API_KEY` | `opencode` |
33
34
  | OpenCode Go | `OPENCODE_API_KEY` | `opencode-go` |
34
35
  | Hugging Face | `HF_TOKEN` | `huggingface` |
36
+ | Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
35
37
  | Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
36
38
  | MiniMax | `MINIMAX_API_KEY` | `minimax` |
37
39
  | MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
40
+ | Moonshot | `MOONSHOT_API_KEY` | `moonshot` |
41
+ | Xiaomi MiMo | `XIAOMI_API_KEY` | `xiaomi` |
42
+ | Xiaomi MiMo Token Plan (CN/AMS/SGP) | `XIAOMI_TOKEN_PLAN_{CN,AMS,SGP}_API_KEY` | `xiaomi-token-plan-{cn,ams,sgp}` |
38
43
 
39
44
  ## Auth File
40
45
 
@@ -68,6 +73,11 @@ Use `/logout` to clear stored OAuth credentials.
68
73
  ```bash
69
74
  export AZURE_OPENAI_API_KEY=...
70
75
  export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
76
+ # Cognitive Services endpoints are also supported and auto-normalized to /openai/v1:
77
+ # export AZURE_OPENAI_BASE_URL=https://your-resource.cognitiveservices.azure.com
78
+ # Or supply the resource name only:
79
+ export AZURE_OPENAI_RESOURCE_NAME=your-resource
80
+
71
81
  export AZURE_OPENAI_API_VERSION=2024-02-01
72
82
  export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4o=my-gpt4o
73
83
  ```
@@ -86,6 +96,18 @@ Useful extras:
86
96
  - `AWS_BEDROCK_FORCE_CACHE=1` for application inference profiles
87
97
  - `AWS_ENDPOINT_URL_BEDROCK_RUNTIME` / `AWS_BEDROCK_SKIP_AUTH` / `AWS_BEDROCK_FORCE_HTTP1` for proxies
88
98
 
99
+ ### Cloudflare AI Gateway / Workers AI
100
+
101
+ `/login` stores `CLOUDFLARE_API_KEY`. Account ID (and gateway slug for AI Gateway) must be set as env vars:
102
+
103
+ ```bash
104
+ export CLOUDFLARE_ACCOUNT_ID=...
105
+ export CLOUDFLARE_GATEWAY_ID=... # AI Gateway only
106
+
107
+ pi --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"
108
+ pi --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"
109
+ ```
110
+
89
111
  ### Google Vertex AI
90
112
 
91
113
  Use ADC:
@@ -114,7 +136,15 @@ Use `models.json` for OpenAI-compatible, Anthropic-compatible, Google-compatible
114
136
  "name": "Llama 3.2",
115
137
  "contextWindow": 128000,
116
138
  "maxTokens": 4096,
117
- "input": ["text"]
139
+ "input": ["text"],
140
+ "thinkingLevelMap": {
141
+ "off": null,
142
+ "minimal": "low",
143
+ "low": "low",
144
+ "medium": "medium",
145
+ "high": "high",
146
+ "xhigh": "high"
147
+ }
118
148
  }
119
149
  ]
120
150
  }
@@ -133,17 +163,36 @@ Common `api` values:
133
163
  - `"mistral-conversations"`
134
164
  - `"bedrock-converse-stream"`
135
165
 
166
+ ### Model & Compatibility Knobs
167
+
168
+ - `thinkingLevelMap` (Pi 0.72) replaces `compat.reasoningEffortMap`. Map pi levels (`off`/`minimal`/`low`/`medium`/`high`/`xhigh`) to provider values; use `null` to hide a level.
169
+ - `openRouterRouting` is forwarded as-is in the OpenRouter `provider` field (fallbacks, ZDR, ignore lists, throughput/latency).
170
+ - Advanced `compat` flags exist for proxy quirks (`cacheControlFormat`, `supportsLongCacheRetention`, `supportsEagerToolInputStreaming`, `sendSessionIdHeader`, `sendSessionAffinityHeaders`). See [pi-mono `docs/models.md`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/models.md) when a proxy rejects pi's defaults.
171
+
136
172
  ## Custom Providers via Extensions
137
173
 
138
- Use extensions when you need custom streaming, custom headers, or OAuth/device-flow logic:
174
+ Use extensions when you need custom streaming, custom headers, OAuth/device-flow logic, or want to override an existing provider's `baseUrl`/`headers`:
139
175
 
140
176
  ```typescript
177
+ // Full registration
141
178
  pi.registerProvider("my-provider", {
179
+ name: "My Provider", // optional friendly /login label
142
180
  baseUrl: "https://api.example.com",
143
181
  api: "openai-completions",
144
182
  apiKey: "MY_PROVIDER_KEY",
145
- models: [{ id: "my-model", name: "My Model", contextWindow: 128000, maxTokens: 4096 }],
183
+ models: [
184
+ {
185
+ id: "my-model",
186
+ name: "My Model",
187
+ contextWindow: 128000,
188
+ maxTokens: 4096,
189
+ baseUrl: "https://us-east.api.example.com", // per-model override
190
+ },
191
+ ],
146
192
  });
193
+
194
+ // Override-only: re-route an existing built-in provider through a proxy
195
+ pi.registerProvider("anthropic", { baseUrl: "https://proxy.example.com" });
147
196
  ```
148
197
 
149
198
  ## SDK / Extension Auth Lookup
package/skills/pi/references/sdk.md CHANGED
@@ -46,9 +46,8 @@ Run with `npx tsx my-script.ts`.
46
46
  import {
47
47
  AuthStorage,
48
48
  createAgentSession,
49
- createCodingTools,
50
- createReadOnlyTools,
51
49
  DefaultResourceLoader,
50
+ defineTool,
52
51
  ModelRegistry,
53
52
  SessionManager,
54
53
  } from "@mariozechner/pi-coding-agent";
@@ -67,22 +66,27 @@ const { session } = await createAgentSession({
67
66
  agentDir: "~/.pi/agent",
68
67
  authStorage,
69
68
  modelRegistry,
70
- model: getModel("anthropic", "claude-sonnet-4-20250514"),
69
+ model: getModel("anthropic", "claude-opus-4-7"),
71
70
  thinkingLevel: "medium",
72
71
  scopedModels: [
73
- { model: getModel("anthropic", "claude-sonnet-4-20250514"), thinkingLevel: "high" },
72
+ { model: getModel("anthropic", "claude-opus-4-7"), thinkingLevel: "high" },
74
73
  ],
75
- tools: createCodingTools(cwd),
74
+ tools: ["read", "bash", "edit", "write"],
75
+ customTools: [/* defineTool(...) entries */],
76
76
  resourceLoader: new DefaultResourceLoader(),
77
77
  sessionManager: SessionManager.inMemory(),
78
+ shouldStopAfterTurn: (state) => state.turnCount >= 5,
78
79
  });
79
80
  ```
80
81
 
81
82
  Notes:
82
83
 
83
84
  - `cwd` and `agentDir` control default resource discovery when using `DefaultResourceLoader`.
84
- - If you provide a custom `cwd` **and** explicit built-in tools, use `createCodingTools(cwd)` / `createReadOnlyTools(cwd)` so paths resolve against that cwd.
85
- - `DefaultResourceLoader` loads extensions, skills, prompt templates, themes, and context files. If you replace it, `cwd` and `agentDir` no longer drive resource discovery.
85
+ - Pi 0.68.0 changed the SDK `tools` option from `Tool[]` to a `string[]` allowlist of built-in, extension, and custom tool names. Use `noTools: "builtin"` to disable built-ins while keeping extension/custom tools enabled, or `noTools: "all"` for none.
86
+ - `customTools` accepts `ToolDefinition[]`. Build them with `defineTool({...})` for full TypeScript inference.
87
+ - The `create*Tool(cwd)` factories still exist for code that needs explicit `AgentTool` instances (e.g. when wiring tools into pi-agent-core directly), but they are no longer the value passed to `createAgentSession({ tools })`.
88
+ - `DefaultResourceLoader` loads extensions, skills, prompt templates, themes, and context files. Replace it to drive resource discovery from custom sources (and it must implement `loadProjectContextFiles()` if you want `AGENTS.md`/`CLAUDE.md` discovery; that helper is also exported standalone).
89
+ - Pass `shouldStopAfterTurn(state) => boolean` (Pi 0.72.0) to exit the agent loop gracefully after a completed turn.
86
90
 
87
91
  ## Prompting & Queueing
88
92
 
@@ -140,6 +144,7 @@ let session = runtime.session;
140
144
  let unsubscribe = session.subscribe(() => {});
141
145
 
142
146
  await runtime.newSession();
147
+ await runtime.fork("entry-id", { position: "at" }); // "before" | "at" — `at` powers /clone
143
148
 
144
149
  unsubscribe();
145
150
  session = runtime.session;
@@ -214,7 +219,7 @@ Use `defineTool()` when you want a reusable custom tool definition outside `pi.r
214
219
 
215
220
  ```typescript
216
221
  import { defineTool } from "@mariozechner/pi-coding-agent";
217
- import { Type } from "@sinclair/typebox";
222
+ import { Type } from "typebox";
218
223
 
219
224
  const myTool = defineTool({
220
225
  name: "my_tool",
@@ -227,7 +232,10 @@ const myTool = defineTool({
227
232
  return {
228
233
  content: [{ type: "text", text: `Result: ${params.input}` }],
229
234
  details: {},
235
+ // terminate: true, // optional — end the tool batch without an automatic follow-up LLM turn
230
236
  };
231
237
  },
232
238
  });
233
239
  ```
240
+
241
+ Pass these via `customTools: [myTool]` on `createAgentSession()` or via `pi.registerTool(myTool)` from inside an extension.
package/skills/pi/references/settings.md CHANGED
@@ -65,7 +65,12 @@ Edit JSON directly or use `/settings` for common interactive options.
65
65
  "enabled": true,
66
66
  "maxRetries": 3,
67
67
  "baseDelayMs": 2000,
68
- "maxDelayMs": 60000
68
+ "maxDelayMs": 60000,
69
+ "provider": {
70
+ "timeoutMs": 0,
71
+ "maxRetries": 0,
72
+ "maxRetryDelayMs": 0
73
+ }
69
74
  }
70
75
  }
71
76
  ```
@@ -73,6 +78,7 @@ Edit JSON directly or use `/settings` for common interactive options.
73
78
  Notes:
74
79
 
75
80
  - `retry.maxDelayMs = 0` disables the cap on server-requested retry delays.
81
+ - `retry.provider.*` (Pi 0.70.1) controls the underlying provider SDK's request timeout and retry/backoff — useful for slow local LLMs and flaky proxies. Pi forwards these into `streamSimple` request options when set.
76
82
  - `branchSummary.skipPrompt` skips the confirmation step when navigating with `/tree`.
77
83
 
78
84
  ## Message Delivery
@@ -94,7 +100,9 @@ Notes:
94
100
  {
95
101
  "terminal": {
96
102
  "showImages": true,
97
- "clearOnShrink": false
103
+ "clearOnShrink": false,
104
+ "showTerminalProgress": false,
105
+ "imageWidthCells": 60
98
106
  },
99
107
  "images": {
100
108
  "autoResize": true,
@@ -107,6 +115,19 @@ Notes:
107
115
  ```
108
116
 
109
117
  - `npmCommand` is argv-style and is used for npm lookup/install operations, including git-package installs.
118
+ - `terminal.showTerminalProgress` (default `false` since Pi 0.70.0) toggles OSC 9;4 progress reporting in supporting terminals (iTerm2, WezTerm, Windows Terminal, Kitty).
119
+ - `terminal.imageWidthCells` (Pi 0.68.1) caps inline tool-output image width in terminal cells.
120
+
121
+ ## Warnings & Telemetry
122
+
123
+ ```json
124
+ {
125
+ "warnings": { "anthropicExtraUsage": true },
126
+ "enableInstallTelemetry": true
127
+ }
128
+ ```
129
+
130
+ `enableInstallTelemetry` sends an anonymous version ping to `pi.dev` once per local changelog advance (interactive mode only). `PI_OFFLINE=1` or `PI_TELEMETRY=0` disable it.
110
131
 
111
132
  ## Sessions, Model Cycling, Markdown
112
133
 
@@ -171,14 +192,66 @@ Arrays support filtering:
171
192
  - `+path` force-includes an exact path
172
193
  - `-path` force-excludes an exact path
173
194
 
195
+ ## CLI Flags
196
+
197
+ Run `pi --help` for the authoritative list. Most commonly:
198
+
199
+ ```text
200
+ pi [options] [@files...] [messages...]
201
+
202
+ # package commands: install/remove/uninstall/update/list/config (all support -l for project scope)
203
+
204
+ # modes
205
+ -p, --print single-shot text output
206
+ --mode json|rpc newline-delimited events / JSON-RPC over stdio
207
+ --export <in> [out] export a session to HTML
208
+
209
+ # model
210
+ --provider <name> e.g. anthropic, openai, google
211
+ --model <pattern> supports provider/id and optional :<thinking>
212
+ --api-key <key>
213
+ --thinking off|minimal|low|medium|high|xhigh
214
+ --models <patterns> Ctrl+P cycling allowlist
215
+ --list-models [search]
216
+
217
+ # sessions
218
+ -c, --continue continue most recent session
219
+ -r, --resume browse and select
220
+ --session <path|id>
221
+ --fork <path|id>
222
+ --session-dir <dir>
223
+ --no-session ephemeral
224
+
225
+ # tools and resources
226
+ --tools <list>, -t name allowlist (read,bash,edit,write,grep,find,ls,...)
227
+ --no-tools, -nt disable everything
228
+ --no-builtin-tools, -nbt disable built-ins, keep extension/custom
229
+ -e, --extension <source> repeatable; npm/git/path
230
+ --skill <path> repeatable
231
+ --prompt-template <path> repeatable
232
+ --theme <path> repeatable
233
+ --no-extensions / --no-skills / --no-prompt-templates / --no-themes
234
+ --no-context-files, -nc skip AGENTS.md / CLAUDE.md discovery
235
+
236
+ # prompts and misc
237
+ --system-prompt <text> replace default
238
+ --append-system-prompt <text> repeatable; appended with double newlines
239
+ --verbose
240
+ ```
241
+
174
242
  ## Environment Variables
175
243
 
176
244
  | Variable | Effect |
177
245
  |----------|--------|
178
246
  | `PI_CODING_AGENT_DIR` | Override the global agent directory |
247
+ | `PI_CODING_AGENT_SESSION_DIR` | Override session storage; `--session-dir` still wins |
179
248
  | `PI_PACKAGE_DIR` | Override package storage directory |
180
- | `PI_SKIP_VERSION_CHECK` | Skip startup version checks |
181
- | `PI_CACHE_RETENTION` | Use extended prompt-cache retention where supported |
249
+ | `PI_SKIP_VERSION_CHECK` | Skip the `pi.dev` latest-version request at startup |
250
+ | `PI_OFFLINE` | Disable all startup network operations (update checks, telemetry) |
251
+ | `PI_TELEMETRY` | Force install telemetry on/off (`1`/`0`); does not gate update checks |
252
+ | `PI_CACHE_RETENTION` | Set to `long` for extended prompt-cache retention where supported |
253
+ | `PI_OAUTH_CALLBACK_HOST` | Bind the OAuth callback server to a custom interface |
254
+ | `PI_CODING_AGENT=true` | Set automatically at startup so subprocesses can detect Pi |
182
255
  | `VISUAL`, `EDITOR` | External editor for `Ctrl+G` |
183
256
  | Provider API key env vars | See `references/providers.md` |
184
257