@dyyz1993/pi-coding-agent 0.70.6 → 0.74.4

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 (275) hide show
  1. package/CHANGELOG.md +266 -80
  2. package/README.md +48 -20
  3. package/dist/bun/cli.d.ts.map +1 -1
  4. package/dist/bun/cli.js +4 -2
  5. package/dist/bun/cli.js.map +1 -1
  6. package/dist/bun/restore-sandbox-env.d.ts +13 -0
  7. package/dist/bun/restore-sandbox-env.d.ts.map +1 -0
  8. package/dist/bun/restore-sandbox-env.js +32 -0
  9. package/dist/bun/restore-sandbox-env.js.map +1 -0
  10. package/dist/cli/args.d.ts +2 -1
  11. package/dist/cli/args.d.ts.map +1 -1
  12. package/dist/cli/args.js +34 -22
  13. package/dist/cli/args.js.map +1 -1
  14. package/dist/cli/list-models.d.ts.map +1 -1
  15. package/dist/cli/list-models.js +2 -1
  16. package/dist/cli/list-models.js.map +1 -1
  17. package/dist/cli.d.ts.map +1 -1
  18. package/dist/cli.js +9 -4
  19. package/dist/cli.js.map +1 -1
  20. package/dist/config.d.ts +16 -8
  21. package/dist/config.d.ts.map +1 -1
  22. package/dist/config.js +238 -66
  23. package/dist/config.js.map +1 -1
  24. package/dist/core/agent-session-runtime.d.ts +10 -0
  25. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  26. package/dist/core/agent-session-runtime.js +14 -0
  27. package/dist/core/agent-session-runtime.js.map +1 -1
  28. package/dist/core/agent-session-services.d.ts +2 -1
  29. package/dist/core/agent-session-services.d.ts.map +1 -1
  30. package/dist/core/agent-session-services.js +1 -0
  31. package/dist/core/agent-session-services.js.map +1 -1
  32. package/dist/core/agent-session.d.ts +25 -26
  33. package/dist/core/agent-session.d.ts.map +1 -1
  34. package/dist/core/agent-session.js +1042 -1116
  35. package/dist/core/agent-session.js.map +1 -1
  36. package/dist/core/auth-guidance.d.ts +5 -0
  37. package/dist/core/auth-guidance.d.ts.map +1 -0
  38. package/dist/core/auth-guidance.js +21 -0
  39. package/dist/core/auth-guidance.js.map +1 -0
  40. package/dist/core/auth-storage.d.ts +9 -0
  41. package/dist/core/auth-storage.d.ts.map +1 -1
  42. package/dist/core/auth-storage.js +20 -1
  43. package/dist/core/auth-storage.js.map +1 -1
  44. package/dist/core/bash-executor.d.ts.map +1 -1
  45. package/dist/core/bash-executor.js +9 -6
  46. package/dist/core/bash-executor.js.map +1 -1
  47. package/dist/core/compaction/compaction.d.ts +0 -1
  48. package/dist/core/compaction/compaction.d.ts.map +1 -1
  49. package/dist/core/compaction/compaction.js.map +1 -1
  50. package/dist/core/export-html/ansi-to-html.d.ts.map +1 -1
  51. package/dist/core/export-html/ansi-to-html.js +1 -1
  52. package/dist/core/export-html/ansi-to-html.js.map +1 -1
  53. package/dist/core/export-html/template.css +53 -4
  54. package/dist/core/export-html/template.js +84 -20
  55. package/dist/core/export-html/tool-renderer.d.ts +0 -6
  56. package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
  57. package/dist/core/export-html/tool-renderer.js +15 -2
  58. package/dist/core/export-html/tool-renderer.js.map +1 -1
  59. package/dist/core/extensions/index.d.ts +1 -1
  60. package/dist/core/extensions/index.d.ts.map +1 -1
  61. package/dist/core/extensions/index.js.map +1 -1
  62. package/dist/core/extensions/loader.d.ts +0 -1
  63. package/dist/core/extensions/loader.d.ts.map +1 -1
  64. package/dist/core/extensions/loader.js +49 -137
  65. package/dist/core/extensions/loader.js.map +1 -1
  66. package/dist/core/extensions/runner.d.ts +24 -20
  67. package/dist/core/extensions/runner.d.ts.map +1 -1
  68. package/dist/core/extensions/runner.js +128 -253
  69. package/dist/core/extensions/runner.js.map +1 -1
  70. package/dist/core/extensions/types.d.ts +88 -60
  71. package/dist/core/extensions/types.d.ts.map +1 -1
  72. package/dist/core/extensions/types.js +10 -0
  73. package/dist/core/extensions/types.js.map +1 -1
  74. package/dist/core/file-store/file-snapshot-manager.d.ts +95 -0
  75. package/dist/core/file-store/file-snapshot-manager.d.ts.map +1 -0
  76. package/dist/core/file-store/file-snapshot-manager.js +508 -0
  77. package/dist/core/file-store/file-snapshot-manager.js.map +1 -0
  78. package/dist/core/file-store/index.d.ts +5 -0
  79. package/dist/core/file-store/index.d.ts.map +1 -0
  80. package/dist/core/file-store/index.js +3 -0
  81. package/dist/core/file-store/index.js.map +1 -0
  82. package/dist/core/messages.d.ts +10 -2
  83. package/dist/core/messages.d.ts.map +1 -1
  84. package/dist/core/messages.js +23 -6
  85. package/dist/core/messages.js.map +1 -1
  86. package/dist/core/model-registry.d.ts +19 -1
  87. package/dist/core/model-registry.d.ts.map +1 -1
  88. package/dist/core/model-registry.js +97 -16
  89. package/dist/core/model-registry.js.map +1 -1
  90. package/dist/core/model-resolver.d.ts.map +1 -1
  91. package/dist/core/model-resolver.js +24 -15
  92. package/dist/core/model-resolver.js.map +1 -1
  93. package/dist/core/package-manager.d.ts +1 -0
  94. package/dist/core/package-manager.d.ts.map +1 -1
  95. package/dist/core/package-manager.js +61 -35
  96. package/dist/core/package-manager.js.map +1 -1
  97. package/dist/core/provider-display-names.d.ts +2 -0
  98. package/dist/core/provider-display-names.d.ts.map +1 -0
  99. package/dist/core/provider-display-names.js +32 -0
  100. package/dist/core/provider-display-names.js.map +1 -0
  101. package/dist/core/resource-loader.d.ts.map +1 -1
  102. package/dist/core/resource-loader.js +9 -21
  103. package/dist/core/resource-loader.js.map +1 -1
  104. package/dist/core/sdk.d.ts +9 -1
  105. package/dist/core/sdk.d.ts.map +1 -1
  106. package/dist/core/sdk.js +39 -18
  107. package/dist/core/sdk.js.map +1 -1
  108. package/dist/core/session-manager.d.ts +27 -17
  109. package/dist/core/session-manager.d.ts.map +1 -1
  110. package/dist/core/session-manager.js +133 -47
  111. package/dist/core/session-manager.js.map +1 -1
  112. package/dist/core/settings-manager.d.ts +21 -3
  113. package/dist/core/settings-manager.d.ts.map +1 -1
  114. package/dist/core/settings-manager.js +51 -6
  115. package/dist/core/settings-manager.js.map +1 -1
  116. package/dist/core/skills.d.ts.map +1 -1
  117. package/dist/core/skills.js +3 -8
  118. package/dist/core/skills.js.map +1 -1
  119. package/dist/core/slash-commands.d.ts.map +1 -1
  120. package/dist/core/slash-commands.js +4 -3
  121. package/dist/core/slash-commands.js.map +1 -1
  122. package/dist/core/tools/bash.d.ts +0 -2
  123. package/dist/core/tools/bash.d.ts.map +1 -1
  124. package/dist/core/tools/bash.js +155 -110
  125. package/dist/core/tools/bash.js.map +1 -1
  126. package/dist/core/tools/edit-diff.d.ts.map +1 -1
  127. package/dist/core/tools/edit-diff.js +3 -2
  128. package/dist/core/tools/edit-diff.js.map +1 -1
  129. package/dist/core/tools/edit.d.ts.map +1 -1
  130. package/dist/core/tools/edit.js +4 -3
  131. package/dist/core/tools/edit.js.map +1 -1
  132. package/dist/core/tools/find.d.ts.map +1 -1
  133. package/dist/core/tools/find.js +1 -1
  134. package/dist/core/tools/find.js.map +1 -1
  135. package/dist/core/tools/grep.d.ts.map +1 -1
  136. package/dist/core/tools/grep.js +1 -1
  137. package/dist/core/tools/grep.js.map +1 -1
  138. package/dist/core/tools/output-accumulator.d.ts +50 -0
  139. package/dist/core/tools/output-accumulator.d.ts.map +1 -0
  140. package/dist/core/tools/output-accumulator.js +178 -0
  141. package/dist/core/tools/output-accumulator.js.map +1 -0
  142. package/dist/core/tools/read.d.ts.map +1 -1
  143. package/dist/core/tools/read.js +70 -13
  144. package/dist/core/tools/read.js.map +1 -1
  145. package/dist/index.d.ts +1 -1
  146. package/dist/index.d.ts.map +1 -1
  147. package/dist/index.js.map +1 -1
  148. package/dist/main.d.ts.map +1 -1
  149. package/dist/main.js +17 -39
  150. package/dist/main.js.map +1 -1
  151. package/dist/migrations.d.ts +1 -1
  152. package/dist/migrations.d.ts.map +1 -1
  153. package/dist/migrations.js +3 -3
  154. package/dist/migrations.js.map +1 -1
  155. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  156. package/dist/modes/interactive/components/config-selector.js +3 -1
  157. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  158. package/dist/modes/interactive/components/extension-selector.d.ts +1 -4
  159. package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
  160. package/dist/modes/interactive/components/extension-selector.js +14 -56
  161. package/dist/modes/interactive/components/extension-selector.js.map +1 -1
  162. package/dist/modes/interactive/components/login-dialog.d.ts +5 -1
  163. package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
  164. package/dist/modes/interactive/components/login-dialog.js +19 -4
  165. package/dist/modes/interactive/components/login-dialog.js.map +1 -1
  166. package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
  167. package/dist/modes/interactive/components/model-selector.js +1 -1
  168. package/dist/modes/interactive/components/model-selector.js.map +1 -1
  169. package/dist/modes/interactive/components/oauth-selector.d.ts +18 -6
  170. package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
  171. package/dist/modes/interactive/components/oauth-selector.js +93 -25
  172. package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
  173. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
  174. package/dist/modes/interactive/components/scoped-models-selector.js +1 -1
  175. package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
  176. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  177. package/dist/modes/interactive/components/session-selector.js +3 -7
  178. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  179. package/dist/modes/interactive/components/settings-selector.d.ts +5 -0
  180. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  181. package/dist/modes/interactive/components/settings-selector.js +53 -1
  182. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  183. package/dist/modes/interactive/interactive-mode.d.ts +20 -4
  184. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  185. package/dist/modes/interactive/interactive-mode.js +423 -186
  186. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  187. package/dist/modes/interactive/theme/dark.json +1 -1
  188. package/dist/modes/interactive/theme/light.json +1 -1
  189. package/dist/modes/print-mode.d.ts +3 -0
  190. package/dist/modes/print-mode.d.ts.map +1 -1
  191. package/dist/modes/print-mode.js +62 -19
  192. package/dist/modes/print-mode.js.map +1 -1
  193. package/dist/modes/rpc/rpc-client.d.ts +80 -60
  194. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  195. package/dist/modes/rpc/rpc-client.js +108 -93
  196. package/dist/modes/rpc/rpc-client.js.map +1 -1
  197. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  198. package/dist/modes/rpc/rpc-mode.js +106 -0
  199. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  200. package/dist/modes/rpc/rpc-types.d.ts +115 -0
  201. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  202. package/dist/modes/rpc/rpc-types.js.map +1 -1
  203. package/dist/package-manager-cli.d.ts.map +1 -1
  204. package/dist/package-manager-cli.js +238 -12
  205. package/dist/package-manager-cli.js.map +1 -1
  206. package/dist/utils/child-process.d.ts +1 -0
  207. package/dist/utils/child-process.d.ts.map +1 -1
  208. package/dist/utils/child-process.js +8 -0
  209. package/dist/utils/child-process.js.map +1 -1
  210. package/dist/utils/clipboard-image.d.ts.map +1 -1
  211. package/dist/utils/clipboard-image.js +2 -2
  212. package/dist/utils/clipboard-image.js.map +1 -1
  213. package/dist/utils/clipboard.d.ts.map +1 -1
  214. package/dist/utils/clipboard.js +84 -45
  215. package/dist/utils/clipboard.js.map +1 -1
  216. package/dist/utils/paths.d.ts +9 -0
  217. package/dist/utils/paths.d.ts.map +1 -1
  218. package/dist/utils/paths.js +31 -0
  219. package/dist/utils/paths.js.map +1 -1
  220. package/dist/utils/pi-user-agent.d.ts +2 -0
  221. package/dist/utils/pi-user-agent.d.ts.map +1 -0
  222. package/dist/utils/pi-user-agent.js +5 -0
  223. package/dist/utils/pi-user-agent.js.map +1 -0
  224. package/dist/utils/structured-output.d.ts +10 -0
  225. package/dist/utils/structured-output.d.ts.map +1 -0
  226. package/dist/utils/structured-output.js +57 -0
  227. package/dist/utils/structured-output.js.map +1 -0
  228. package/dist/utils/tools-manager.d.ts.map +1 -1
  229. package/dist/utils/tools-manager.js +6 -2
  230. package/dist/utils/tools-manager.js.map +1 -1
  231. package/dist/utils/version-check.d.ts +14 -0
  232. package/dist/utils/version-check.d.ts.map +1 -0
  233. package/dist/utils/version-check.js +77 -0
  234. package/dist/utils/version-check.js.map +1 -0
  235. package/docs/compaction.md +14 -14
  236. package/docs/custom-provider.md +40 -31
  237. package/docs/development.md +1 -1
  238. package/docs/docs.json +148 -0
  239. package/docs/extensions.md +116 -56
  240. package/docs/index.md +70 -0
  241. package/docs/json.md +4 -4
  242. package/docs/models.md +150 -3
  243. package/docs/packages.md +10 -5
  244. package/docs/providers.md +62 -17
  245. package/docs/quickstart.md +142 -0
  246. package/docs/rollback-architecture.md +693 -0
  247. package/docs/rollback-test-cases.md +412 -0
  248. package/docs/rpc.md +1 -1
  249. package/docs/sdk.md +26 -26
  250. package/docs/{session.md → session-format.md} +6 -6
  251. package/docs/sessions.md +137 -0
  252. package/docs/settings.md +52 -9
  253. package/docs/termux.md +1 -1
  254. package/docs/themes.md +2 -2
  255. package/docs/tui.md +20 -20
  256. package/docs/usage.md +277 -0
  257. package/examples/extensions/README.md +2 -4
  258. package/examples/extensions/border-status-editor.ts +150 -0
  259. package/examples/extensions/commands.ts +2 -2
  260. package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
  261. package/examples/extensions/custom-provider-anthropic/package.json +1 -1
  262. package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  263. package/examples/extensions/dynamic-resources/dynamic.json +1 -1
  264. package/examples/extensions/git-checkpoint.ts +1 -1
  265. package/examples/extensions/handoff.ts +49 -11
  266. package/examples/extensions/plan-mode/index.ts +1 -1
  267. package/examples/extensions/sandbox/package-lock.json +5 -5
  268. package/examples/extensions/sandbox/package.json +1 -1
  269. package/examples/extensions/subagent/agents.ts +126 -0
  270. package/examples/extensions/with-deps/package-lock.json +2 -2
  271. package/examples/extensions/with-deps/package.json +1 -1
  272. package/examples/sdk/README.md +2 -2
  273. package/package.json +7 -16
  274. package/docs/tree.md +0 -233
  275. package/examples/extensions/antigravity-image-gen.ts +0 -418
package/docs/usage.md ADDED
@@ -0,0 +1,277 @@
1
+ # Using Pi
2
+
3
+ This page collects day-to-day usage details that do not fit on the quickstart page.
4
+
5
+ ## Interactive Mode
6
+
7
+ <p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
8
+
9
+ The interface has four main areas:
10
+
11
+ - **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
12
+ - **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
13
+ - **Editor** - where you type; border color indicates the current thinking level
14
+ - **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model
15
+
16
+ The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI.
17
+
18
+ ### Editor Features
19
+
20
+ | Feature | How |
21
+ |---------|-----|
22
+ | File reference | Type `@` to fuzzy-search project files |
23
+ | Path completion | Press Tab to complete paths |
24
+ | Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
25
+ | Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
26
+ | Shell command | `!command` runs and sends output to the model |
27
+ | Hidden shell command | `!!command` runs without sending output to the model |
28
+ | External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` |
29
+
30
+ See [Keybindings](keybindings.md) for all shortcuts and customization.
31
+
32
+ ## Slash Commands
33
+
34
+ Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
35
+
36
+ | Command | Description |
37
+ |---------|-------------|
38
+ | `/login`, `/logout` | Manage OAuth or API-key credentials |
39
+ | `/model` | Switch models |
40
+ | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
41
+ | `/settings` | Thinking level, theme, message delivery, transport |
42
+ | `/resume` | Pick from previous sessions |
43
+ | `/new` | Start a new session |
44
+ | `/name <name>` | Set session display name |
45
+ | `/session` | Show session file, ID, messages, tokens, and cost |
46
+ | `/tree` | Jump to any point in the session and continue from there |
47
+ | `/fork` | Create a new session from a previous user message |
48
+ | `/clone` | Duplicate the current active branch into a new session |
49
+ | `/compact [prompt]` | Manually compact context, optionally with custom instructions |
50
+ | `/copy` | Copy last assistant message to clipboard |
51
+ | `/export [file]` | Export session to HTML |
52
+ | `/share` | Upload as private GitHub gist with shareable HTML link |
53
+ | `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
54
+ | `/hotkeys` | Show all keyboard shortcuts |
55
+ | `/changelog` | Display version history |
56
+ | `/quit` | Quit pi |
57
+
58
+ ## Message Queue
59
+
60
+ You can submit messages while the agent is still working:
61
+
62
+ - **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
63
+ - **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
64
+ - **Escape** aborts and restores queued messages to the editor.
65
+ - **Alt+Up** retrieves queued messages back to the editor.
66
+
67
+ On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want pi to receive the shortcut.
68
+
69
+ Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
70
+
71
+ ## Sessions
72
+
73
+ Sessions are saved automatically to `~/.pi/agent/sessions/`, organized by working directory.
74
+
75
+ ```bash
76
+ pi -c # Continue most recent session
77
+ pi -r # Browse and select a session
78
+ pi --no-session # Ephemeral mode; do not save
79
+ pi --session <path|id> # Use a specific session file or session ID
80
+ pi --fork <path|id> # Fork a session into a new session file
81
+ ```
82
+
83
+ Useful session commands:
84
+
85
+ - `/session` shows the current session file and ID.
86
+ - `/tree` navigates the in-file session tree and can summarize abandoned branches.
87
+ - `/fork` creates a new session from an earlier user message.
88
+ - `/clone` duplicates the current active branch into a new session file.
89
+ - `/compact` summarizes older messages to free context.
90
+
91
+ See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
92
+
93
+ ## Context Files
94
+
95
+ Pi loads `AGENTS.md` or `CLAUDE.md` at startup from:
96
+
97
+ - `~/.pi/agent/AGENTS.md` for global instructions
98
+ - parent directories, walking up from the current working directory
99
+ - the current directory
100
+
101
+ Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
102
+
103
+ ### System Prompt Files
104
+
105
+ Replace the default system prompt with:
106
+
107
+ - `.pi/SYSTEM.md` for a project
108
+ - `~/.pi/agent/SYSTEM.md` globally
109
+
110
+ Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
111
+
112
+ ## Exporting and Sharing Sessions
113
+
114
+ Use `/export [file]` to write a session to HTML.
115
+
116
+ Use `/share` to upload a private GitHub gist with a shareable HTML link.
117
+
118
+ If you use pi for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). It publishes sessions to Hugging Face datasets.
119
+
120
+ ## CLI Reference
121
+
122
+ ```bash
123
+ pi [options] [@files...] [messages...]
124
+ ```
125
+
126
+ ### Package Commands
127
+
128
+ ```bash
129
+ pi install <source> [-l] # Install package, -l for project-local
130
+ pi remove <source> [-l] # Remove package
131
+ pi uninstall <source> [-l] # Alias for remove
132
+ pi update [source|self|pi] # Update pi and packages; skips pinned packages
133
+ pi update --extensions # Update packages only
134
+ pi update --self # Update pi only
135
+ pi update --extension <src> # Update one package
136
+ pi list # List installed packages
137
+ pi config # Enable/disable package resources
138
+ ```
139
+
140
+ See [Pi Packages](packages.md) for package sources and security notes.
141
+
142
+ ### Modes
143
+
144
+ | Flag | Description |
145
+ |------|-------------|
146
+ | default | Interactive mode |
147
+ | `-p`, `--print` | Print response and exit |
148
+ | `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
149
+ | `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
150
+ | `--export <in> [out]` | Export a session to HTML |
151
+
152
+ In print mode, pi also reads piped stdin and merges it into the initial prompt:
153
+
154
+ ```bash
155
+ cat README.md | pi -p "Summarize this text"
156
+ ```
157
+
158
+ ### Model Options
159
+
160
+ | Option | Description |
161
+ |--------|-------------|
162
+ | `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
163
+ | `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
164
+ | `--api-key <key>` | API key, overriding environment variables |
165
+ | `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
166
+ | `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
167
+ | `--list-models [search]` | List available models |
168
+
169
+ ### Session Options
170
+
171
+ | Option | Description |
172
+ |--------|-------------|
173
+ | `-c`, `--continue` | Continue the most recent session |
174
+ | `-r`, `--resume` | Browse and select a session |
175
+ | `--session <path\|id>` | Use a specific session file or partial UUID |
176
+ | `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
177
+ | `--session-dir <dir>` | Custom session storage directory |
178
+ | `--no-session` | Ephemeral mode; do not save |
179
+
180
+ ### Tool Options
181
+
182
+ | Option | Description |
183
+ |--------|-------------|
184
+ | `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
185
+ | `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
186
+ | `--no-tools`, `-nt` | Disable all tools |
187
+
188
+ Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
189
+
190
+ ### Resource Options
191
+
192
+ | Option | Description |
193
+ |--------|-------------|
194
+ | `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
195
+ | `--no-extensions` | Disable extension discovery |
196
+ | `--skill <path>` | Load a skill; repeatable |
197
+ | `--no-skills` | Disable skill discovery |
198
+ | `--prompt-template <path>` | Load a prompt template; repeatable |
199
+ | `--no-prompt-templates` | Disable prompt template discovery |
200
+ | `--theme <path>` | Load a theme; repeatable |
201
+ | `--no-themes` | Disable theme discovery |
202
+ | `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
203
+
204
+ Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
205
+
206
+ ```bash
207
+ pi --no-extensions -e ./my-extension.ts
208
+ ```
209
+
210
+ ### Other Options
211
+
212
+ | Option | Description |
213
+ |--------|-------------|
214
+ | `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
215
+ | `--append-system-prompt <text>` | Append to system prompt |
216
+ | `--verbose` | Force verbose startup |
217
+ | `-h`, `--help` | Show help |
218
+ | `-v`, `--version` | Show version |
219
+
220
+ ### File Arguments
221
+
222
+ Prefix files with `@` to include them in the message:
223
+
224
+ ```bash
225
+ pi @prompt.md "Answer this"
226
+ pi -p @screenshot.png "What's in this image?"
227
+ pi @code.ts @test.ts "Review these files"
228
+ ```
229
+
230
+ ### Examples
231
+
232
+ ```bash
233
+ # Interactive with initial prompt
234
+ pi "List all .ts files in src/"
235
+
236
+ # Non-interactive
237
+ pi -p "Summarize this codebase"
238
+
239
+ # Non-interactive with piped stdin
240
+ cat README.md | pi -p "Summarize this text"
241
+
242
+ # Different model
243
+ pi --provider openai --model gpt-4o "Help me refactor"
244
+
245
+ # Model with provider prefix
246
+ pi --model openai/gpt-4o "Help me refactor"
247
+
248
+ # Model with thinking level shorthand
249
+ pi --model sonnet:high "Solve this complex problem"
250
+
251
+ # Limit model cycling
252
+ pi --models "claude-*,gpt-4o"
253
+
254
+ # Read-only mode
255
+ pi --tools read,grep,find,ls -p "Review the code"
256
+ ```
257
+
258
+ ### Environment Variables
259
+
260
+ | Variable | Description |
261
+ |----------|-------------|
262
+ | `PI_CODING_AGENT_DIR` | Override config directory; default is `~/.pi/agent` |
263
+ | `PI_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
264
+ | `PI_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
265
+ | `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
266
+ | `PI_SKIP_VERSION_CHECK` | Skip the Pi version update check at startup. This prevents the `pi.dev` latest-version request |
267
+ | `PI_TELEMETRY` | Override install/update telemetry: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
268
+ | `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
269
+ | `VISUAL`, `EDITOR` | External editor for Ctrl+G |
270
+
271
+ ## Design Principles
272
+
273
+ Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
274
+
275
+ It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
276
+
277
+ For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).
@@ -38,7 +38,6 @@ cp permission-gate.ts ~/.pi/agent/extensions/
38
38
  | `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools (read, bash, edit, write) while keeping original behavior |
39
39
  | `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |
40
40
  | `truncated-tool.ts` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |
41
- | `antigravity-image-gen.ts` | Generate images via Google Antigravity with optional save-to-disk modes |
42
41
  | `ssh.ts` | Delegate all tools to a remote machine via SSH using pluggable operations |
43
42
  | `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
44
43
 
@@ -126,7 +125,6 @@ cp permission-gate.ts ~/.pi/agent/extensions/
126
125
  |-----------|-------------|
127
126
  | `custom-provider-anthropic/` | Custom Anthropic provider with OAuth support and custom streaming implementation |
128
127
  | `custom-provider-gitlab-duo/` | GitLab Duo provider using pi-ai's built-in Anthropic/OpenAI streaming via proxy |
129
- | `custom-provider-qwen-cli/` | Qwen CLI provider with OAuth device flow and OpenAI-compatible models |
130
128
 
131
129
  ### External Dependencies
132
130
 
@@ -140,7 +138,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
140
138
  See [docs/extensions.md](../../docs/extensions.md) for full documentation.
141
139
 
142
140
  ```typescript
143
- import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
141
+ import type { ExtensionAPI } from "@dyyz1993/pi-coding-agent";
144
142
  import { Type } from "typebox";
145
143
 
146
144
  export default function (pi: ExtensionAPI) {
@@ -182,7 +180,7 @@ export default function (pi: ExtensionAPI) {
182
180
 
183
181
  **Use StringEnum for string parameters** (required for Google API compatibility):
184
182
  ```typescript
185
- import { StringEnum } from "@mariozechner/pi-ai";
183
+ import { StringEnum } from "@dyyz1993/pi-ai";
186
184
 
187
185
  // Good
188
186
  action: StringEnum(["list", "add"] as const)
@@ -0,0 +1,150 @@
1
+ import {
2
+ CustomEditor,
3
+ type ExtensionAPI,
4
+ type ExtensionContext,
5
+ type KeybindingsManager,
6
+ } from "@dyyz1993/pi-coding-agent";
7
+ import type { Component, EditorTheme, TUI } from "@dyyz1993/pi-tui";
8
+ import { truncateToWidth, visibleWidth } from "@dyyz1993/pi-tui";
9
+
10
+ function fitBorder(
11
+ left: string,
12
+ right: string,
13
+ width: number,
14
+ border: (text: string) => string,
15
+ fill: (text: string) => string = border,
16
+ ): string {
17
+ if (width <= 0) return "";
18
+ if (width === 1) return border("─");
19
+
20
+ let leftText = left;
21
+ let rightText = right;
22
+ const fixedWidth = 2;
23
+ const minimumGap = 3;
24
+
25
+ while (
26
+ fixedWidth + visibleWidth(leftText) + visibleWidth(rightText) + minimumGap > width &&
27
+ visibleWidth(rightText) > 0
28
+ ) {
29
+ rightText = truncateToWidth(rightText, Math.max(0, visibleWidth(rightText) - 1), "");
30
+ }
31
+ while (
32
+ fixedWidth + visibleWidth(leftText) + visibleWidth(rightText) + minimumGap > width &&
33
+ visibleWidth(leftText) > 0
34
+ ) {
35
+ leftText = truncateToWidth(leftText, Math.max(0, visibleWidth(leftText) - 1), "");
36
+ }
37
+
38
+ const gapWidth = Math.max(0, width - fixedWidth - visibleWidth(leftText) - visibleWidth(rightText));
39
+ return `${border("─")}${leftText}${fill("─".repeat(gapWidth))}${rightText}${border("─")}`;
40
+ }
41
+
42
+ function formatCwd(cwd: string): string {
43
+ const home = process.env.HOME;
44
+ if (home && cwd.startsWith(home)) {
45
+ return `~${cwd.slice(home.length)}`;
46
+ }
47
+ return cwd;
48
+ }
49
+
50
+ function formatContext(ctx: ExtensionContext): string {
51
+ const usage = ctx.getContextUsage();
52
+ const contextWindow = usage?.contextWindow ?? ctx.model?.contextWindow;
53
+ if (!contextWindow || !usage || usage.percent === null) {
54
+ return "ctx ?";
55
+ }
56
+ return `ctx ${Math.round(usage.percent)}%/${(contextWindow / 1000).toFixed(0)}k`;
57
+ }
58
+
59
+ function formatThinking(level: string): string {
60
+ return level === "off" ? "off" : level;
61
+ }
62
+
63
+ class EmptyFooter implements Component {
64
+ render(): string[] {
65
+ return [];
66
+ }
67
+
68
+ invalidate(): void {}
69
+ }
70
+
71
+ export default function (pi: ExtensionAPI) {
72
+ let isWorking = false;
73
+ let spinnerIndex = 0;
74
+ let spinnerTimer: ReturnType<typeof setInterval> | undefined;
75
+ let activeTui: TUI | undefined;
76
+ const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
77
+
78
+ const stopSpinner = () => {
79
+ if (spinnerTimer) {
80
+ clearInterval(spinnerTimer);
81
+ spinnerTimer = undefined;
82
+ }
83
+ };
84
+
85
+ pi.on("agent_start", () => {
86
+ isWorking = true;
87
+ stopSpinner();
88
+ spinnerTimer = setInterval(() => {
89
+ spinnerIndex = (spinnerIndex + 1) % spinnerFrames.length;
90
+ activeTui?.requestRender();
91
+ }, 80);
92
+ activeTui?.requestRender();
93
+ });
94
+
95
+ pi.on("agent_end", () => {
96
+ isWorking = false;
97
+ stopSpinner();
98
+ activeTui?.requestRender();
99
+ });
100
+
101
+ pi.on("session_shutdown", () => {
102
+ stopSpinner();
103
+ activeTui = undefined;
104
+ });
105
+
106
+ pi.on("session_start", (_event, ctx) => {
107
+ ctx.ui.setWorkingVisible(false);
108
+ ctx.ui.setFooter(() => new EmptyFooter());
109
+
110
+ let branch: string | undefined;
111
+
112
+ const refreshBranch = async () => {
113
+ const result = await pi.exec("git", ["branch", "--show-current"], { cwd: ctx.cwd }).catch(() => undefined);
114
+ const stdout = result?.stdout.trim();
115
+ branch = stdout && stdout.length > 0 ? stdout : undefined;
116
+ activeTui?.requestRender();
117
+ };
118
+ void refreshBranch();
119
+
120
+ class BorderStatusEditor extends CustomEditor {
121
+ constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) {
122
+ super(tui, theme, keybindings, { paddingX: 0 });
123
+ activeTui = tui;
124
+ }
125
+
126
+ render(width: number): string[] {
127
+ const lines = super.render(width);
128
+ if (lines.length < 2) return lines;
129
+
130
+ const thm = ctx.ui.theme;
131
+ const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "no model";
132
+ const thinking = pi.getThinkingLevel();
133
+ const topLeft = isWorking ? thm.fg("accent", ` ${spinnerFrames[spinnerIndex]} `) : "";
134
+ const topRight = "";
135
+ const bottomLeft = thm.fg("muted", ` ${model} · ${formatThinking(thinking)} `);
136
+ const bottomRight = thm.fg(
137
+ "muted",
138
+ ` ${formatContext(ctx)} · ${formatCwd(ctx.cwd)}${branch ? ` (${branch})` : ""} `,
139
+ );
140
+ const borderColor = (text: string) => this.borderColor(text);
141
+
142
+ lines[0] = fitBorder(topLeft, topRight, width, borderColor);
143
+ lines[lines.length - 1] = fitBorder(bottomLeft, bottomRight, width, borderColor);
144
+ return lines;
145
+ }
146
+ }
147
+
148
+ ctx.ui.setEditorComponent((tui, theme, keybindings) => new BorderStatusEditor(tui, theme, keybindings));
149
+ });
150
+ }
@@ -57,8 +57,8 @@ export default function commandsExtension(pi: ExtensionAPI) {
57
57
  const selected = await ctx.ui.select("Available Commands", items);
58
58
 
59
59
  // If user selected a command (not a header), offer to show its path
60
- if (selected && !selected.startsWith("---")) {
61
- const cmdName = selected.split(" - ")[0].slice(1); // Remove leading /
60
+ if (selected && typeof selected === "string" && !selected.startsWith("---")) {
61
+ const cmdName = selected.split(" - ")[0].slice(1);
62
62
  const cmd = commands.find((c) => c.name === cmdName);
63
63
  if (cmd?.sourceInfo.path) {
64
64
  const showPath = await ctx.ui.confirm(cmd.name, `View source path?\n${cmd.sourceInfo.path}`);
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-extension-custom-provider",
3
- "version": "0.69.26",
3
+ "version": "0.74.4",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-extension-custom-provider",
9
- "version": "0.69.26",
9
+ "version": "0.74.4",
10
10
  "dependencies": {
11
11
  "@anthropic-ai/sdk": "^0.52.0"
12
12
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-extension-custom-provider-anthropic",
3
3
  "private": true,
4
- "version": "0.69.26",
4
+ "version": "0.74.4",
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "clean": "echo 'nothing to clean'",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-extension-custom-provider-gitlab-duo",
3
3
  "private": true,
4
- "version": "0.69.26",
4
+ "version": "0.74.4",
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "clean": "echo 'nothing to clean'",
@@ -1,5 +1,5 @@
1
1
  {
2
- "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
2
+ "$schema": "https://raw.githubusercontent.com/dyyz1993/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
3
3
  "name": "dynamic-resources",
4
4
  "vars": {
5
5
  "cyan": "#00d7ff",
@@ -40,7 +40,7 @@ export default function (pi: ExtensionAPI) {
40
40
  "No, keep current code",
41
41
  ]);
42
42
 
43
- if (choice?.startsWith("Yes")) {
43
+ if (typeof choice === "string" && choice.startsWith("Yes")) {
44
44
  await pi.exec("git", ["stash", "apply", ref]);
45
45
  ctx.ui.notify("Code restored to checkpoint", "info");
46
46
  }
@@ -12,6 +12,7 @@
12
12
  * The generated prompt appears as a draft in the editor for review/editing.
13
13
  */
14
14
 
15
+ import type { AgentMessage } from "@dyyz1993/pi-agent-core";
15
16
  import { complete, type Message } from "@dyyz1993/pi-ai";
16
17
  import type { ExtensionAPI, SessionEntry } from "@dyyz1993/pi-coding-agent";
17
18
  import { BorderedLoader, convertToLlm, serializeConversation } from "@dyyz1993/pi-coding-agent";
@@ -38,6 +39,44 @@ Files involved:
38
39
  ## Task
39
40
  [Clear description of what to do next based on user's goal]`;
40
41
 
42
+ function entryToMessage(entry: SessionEntry): AgentMessage | undefined {
43
+ if (entry.type === "message") {
44
+ return entry.message;
45
+ }
46
+ if (entry.type === "compaction") {
47
+ return {
48
+ role: "compactionSummary",
49
+ summary: entry.summary,
50
+ tokensBefore: entry.tokensBefore,
51
+ timestamp: new Date(entry.timestamp).getTime(),
52
+ };
53
+ }
54
+ return undefined;
55
+ }
56
+
57
+ function getHandoffMessages(branch: SessionEntry[]): AgentMessage[] {
58
+ let compactionIndex = -1;
59
+ for (let i = branch.length - 1; i >= 0; i--) {
60
+ if (branch[i].type === "compaction") {
61
+ compactionIndex = i;
62
+ break;
63
+ }
64
+ }
65
+ if (compactionIndex < 0) {
66
+ return branch.map(entryToMessage).filter((message) => message !== undefined);
67
+ }
68
+
69
+ const compaction = branch[compactionIndex];
70
+ const firstKeptIndex =
71
+ compaction.type === "compaction" ? branch.findIndex((entry) => entry.id === compaction.firstKeptEntryId) : -1;
72
+ const compactedBranch = [
73
+ compaction,
74
+ ...(firstKeptIndex >= 0 ? branch.slice(firstKeptIndex, compactionIndex) : []),
75
+ ...branch.slice(compactionIndex + 1),
76
+ ];
77
+ return compactedBranch.map(entryToMessage).filter((message) => message !== undefined);
78
+ }
79
+
41
80
  export default function (pi: ExtensionAPI) {
42
81
  pi.registerCommand("handoff", {
43
82
  description: "Transfer context to a new focused session",
@@ -58,11 +97,9 @@ export default function (pi: ExtensionAPI) {
58
97
  return;
59
98
  }
60
99
 
61
- // Gather conversation context from current branch
62
- const branch = ctx.sessionManager.getBranch();
63
- const messages = branch
64
- .filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
65
- .map((entry) => entry.message);
100
+ // Gather conversation context from current branch. If the branch was compacted,
101
+ // include the compaction summary plus entries from firstKeptEntryId onward.
102
+ const messages = getHandoffMessages(ctx.sessionManager.getBranch());
66
103
 
67
104
  if (messages.length === 0) {
68
105
  ctx.ui.notify("No conversation to hand off", "error");
@@ -135,19 +172,20 @@ export default function (pi: ExtensionAPI) {
135
172
  return;
136
173
  }
137
174
 
138
- // Create new session with parent tracking
175
+ // Create new session with parent tracking. Use the replacement-session
176
+ // context for post-switch UI work; the original ctx is stale after a
177
+ // successful session replacement.
139
178
  const newSessionResult = await ctx.newSession({
140
179
  parentSession: currentSessionFile,
180
+ withSession: async (replacementCtx) => {
181
+ replacementCtx.ui.setEditorText(editedPrompt);
182
+ replacementCtx.ui.notify("Handoff ready. Submit when ready.", "info");
183
+ },
141
184
  });
142
185
 
143
186
  if (newSessionResult.cancelled) {
144
187
  ctx.ui.notify("New session cancelled", "info");
145
- return;
146
188
  }
147
-
148
- // Set the edited prompt in the main editor for submission
149
- ctx.ui.setEditorText(editedPrompt);
150
- ctx.ui.notify("Handoff ready. Submit when ready.", "info");
151
189
  },
152
190
  });
153
191
  }
@@ -265,7 +265,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
265
265
  "Refine the plan",
266
266
  ]);
267
267
 
268
- if (choice?.startsWith("Execute")) {
268
+ if (typeof choice === "string" && choice.startsWith("Execute")) {
269
269
  planModeEnabled = false;
270
270
  executionMode = todoItems.length > 0;
271
271
  pi.setActiveTools(NORMAL_MODE_TOOLS);
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-extension-sandbox",
3
- "version": "1.0.0",
3
+ "version": "1.4.4",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-extension-sandbox",
9
- "version": "1.0.0",
9
+ "version": "1.4.4",
10
10
  "dependencies": {
11
11
  "@anthropic-ai/sandbox-runtime": "^0.0.26"
12
12
  }
@@ -62,9 +62,9 @@
62
62
  }
63
63
  },
64
64
  "node_modules/lodash-es": {
65
- "version": "4.17.22",
66
- "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.22.tgz",
67
- "integrity": "sha512-XEawp1t0gxSi9x01glktRZ5HDy0HXqrM0x5pXQM98EaI0NxO6jVM7omDOxsuEo5UIASAnm2bRp1Jt/e0a2XU8Q==",
65
+ "version": "4.18.1",
66
+ "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.18.1.tgz",
67
+ "integrity": "sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==",
68
68
  "license": "MIT"
69
69
  },
70
70
  "node_modules/shell-quote": {
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-extension-sandbox",
3
3
  "private": true,
4
- "version": "1.0.0",
4
+ "version": "1.4.4",
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "clean": "echo 'nothing to clean'",