@draht/coding-agent 2026.5.12 → 2026.6.11

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 (605) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/bin/draht-tools.cjs +3756 -1
  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 +9 -4
  11. package/dist/cli/args.d.ts.map +1 -1
  12. package/dist/cli/args.js +88 -35
  13. package/dist/cli/args.js.map +1 -1
  14. package/dist/cli/config-selector.d.ts +2 -2
  15. package/dist/cli/config-selector.d.ts.map +1 -1
  16. package/dist/cli/config-selector.js +1 -1
  17. package/dist/cli/config-selector.js.map +1 -1
  18. package/dist/cli/file-processor.d.ts.map +1 -1
  19. package/dist/cli/file-processor.js +2 -3
  20. package/dist/cli/file-processor.js.map +1 -1
  21. package/dist/cli/initial-message.d.ts +1 -1
  22. package/dist/cli/initial-message.d.ts.map +1 -1
  23. package/dist/cli/initial-message.js.map +1 -1
  24. package/dist/cli/list-models.d.ts +1 -1
  25. package/dist/cli/list-models.d.ts.map +1 -1
  26. package/dist/cli/list-models.js +7 -1
  27. package/dist/cli/list-models.js.map +1 -1
  28. package/dist/cli/project-trust.d.ts +10 -0
  29. package/dist/cli/project-trust.d.ts.map +1 -0
  30. package/dist/cli/project-trust.js +48 -0
  31. package/dist/cli/project-trust.js.map +1 -0
  32. package/dist/cli/session-picker.d.ts +1 -1
  33. package/dist/cli/session-picker.d.ts.map +1 -1
  34. package/dist/cli/session-picker.js.map +1 -1
  35. package/dist/cli/startup-ui.d.ts +16 -0
  36. package/dist/cli/startup-ui.d.ts.map +1 -0
  37. package/dist/cli/startup-ui.js +112 -0
  38. package/dist/cli/startup-ui.js.map +1 -0
  39. package/dist/cli.d.ts.map +1 -1
  40. package/dist/cli.js +7 -4
  41. package/dist/cli.js.map +1 -1
  42. package/dist/config.d.ts +23 -13
  43. package/dist/config.d.ts.map +1 -1
  44. package/dist/config.js +264 -62
  45. package/dist/config.js.map +1 -1
  46. package/dist/core/agent-session-runtime.d.ts +45 -9
  47. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  48. package/dist/core/agent-session-runtime.js +100 -33
  49. package/dist/core/agent-session-runtime.js.map +1 -1
  50. package/dist/core/agent-session-services.d.ts +6 -4
  51. package/dist/core/agent-session-services.d.ts.map +1 -1
  52. package/dist/core/agent-session-services.js +7 -4
  53. package/dist/core/agent-session-services.js.map +1 -1
  54. package/dist/core/agent-session.d.ts +47 -31
  55. package/dist/core/agent-session.d.ts.map +1 -1
  56. package/dist/core/agent-session.js +470 -443
  57. package/dist/core/agent-session.js.map +1 -1
  58. package/dist/core/auth-guidance.d.ts +5 -0
  59. package/dist/core/auth-guidance.d.ts.map +1 -0
  60. package/dist/core/auth-guidance.js +21 -0
  61. package/dist/core/auth-guidance.js.map +1 -0
  62. package/dist/core/auth-storage.d.ts +10 -1
  63. package/dist/core/auth-storage.d.ts.map +1 -1
  64. package/dist/core/auth-storage.js +27 -6
  65. package/dist/core/auth-storage.js.map +1 -1
  66. package/dist/core/bash-executor.d.ts +1 -15
  67. package/dist/core/bash-executor.d.ts.map +1 -1
  68. package/dist/core/bash-executor.js +10 -24
  69. package/dist/core/bash-executor.js.map +1 -1
  70. package/dist/core/builtins/subagent.d.ts.map +1 -1
  71. package/dist/core/builtins/subagent.js +1 -2
  72. package/dist/core/builtins/subagent.js.map +1 -1
  73. package/dist/core/compaction/branch-summarization.d.ts +6 -4
  74. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  75. package/dist/core/compaction/branch-summarization.js +9 -3
  76. package/dist/core/compaction/branch-summarization.js.map +1 -1
  77. package/dist/core/compaction/compaction.d.ts +5 -5
  78. package/dist/core/compaction/compaction.d.ts.map +1 -1
  79. package/dist/core/compaction/compaction.js +43 -37
  80. package/dist/core/compaction/compaction.js.map +1 -1
  81. package/dist/core/compaction/index.d.ts +3 -3
  82. package/dist/core/compaction/index.d.ts.map +1 -1
  83. package/dist/core/compaction/index.js.map +1 -1
  84. package/dist/core/compaction/utils.d.ts +1 -1
  85. package/dist/core/compaction/utils.d.ts.map +1 -1
  86. package/dist/core/compaction/utils.js +1 -1
  87. package/dist/core/compaction/utils.js.map +1 -1
  88. package/dist/core/exec.d.ts.map +1 -1
  89. package/dist/core/exec.js.map +1 -1
  90. package/dist/core/experimental.d.ts +2 -0
  91. package/dist/core/experimental.d.ts.map +1 -0
  92. package/dist/core/experimental.js +4 -0
  93. package/dist/core/experimental.js.map +1 -0
  94. package/dist/core/export-html/ansi-to-html.d.ts.map +1 -1
  95. package/dist/core/export-html/ansi-to-html.js +1 -1
  96. package/dist/core/export-html/ansi-to-html.js.map +1 -1
  97. package/dist/core/export-html/index.d.ts +1 -1
  98. package/dist/core/export-html/index.d.ts.map +1 -1
  99. package/dist/core/export-html/index.js +13 -11
  100. package/dist/core/export-html/index.js.map +1 -1
  101. package/dist/core/export-html/template.css +69 -4
  102. package/dist/core/export-html/template.js +231 -57
  103. package/dist/core/export-html/tool-renderer.d.ts +0 -6
  104. package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
  105. package/dist/core/export-html/tool-renderer.js +15 -2
  106. package/dist/core/export-html/tool-renderer.js.map +1 -1
  107. package/dist/core/extensions/index.d.ts +8 -8
  108. package/dist/core/extensions/index.d.ts.map +1 -1
  109. package/dist/core/extensions/index.js.map +1 -1
  110. package/dist/core/extensions/loader.d.ts +3 -3
  111. package/dist/core/extensions/loader.d.ts.map +1 -1
  112. package/dist/core/extensions/loader.js +27 -35
  113. package/dist/core/extensions/loader.js.map +1 -1
  114. package/dist/core/extensions/runner.d.ts +30 -12
  115. package/dist/core/extensions/runner.d.ts.map +1 -1
  116. package/dist/core/extensions/runner.js +215 -32
  117. package/dist/core/extensions/runner.js.map +1 -1
  118. package/dist/core/extensions/types.d.ts +163 -35
  119. package/dist/core/extensions/types.d.ts.map +1 -1
  120. package/dist/core/extensions/types.js.map +1 -1
  121. package/dist/core/extensions/wrapper.d.ts.map +1 -1
  122. package/dist/core/extensions/wrapper.js +2 -2
  123. package/dist/core/extensions/wrapper.js.map +1 -1
  124. package/dist/core/footer-data-provider.d.ts +7 -1
  125. package/dist/core/footer-data-provider.d.ts.map +1 -1
  126. package/dist/core/footer-data-provider.js +78 -54
  127. package/dist/core/footer-data-provider.js.map +1 -1
  128. package/dist/core/http-dispatcher.d.ts +21 -0
  129. package/dist/core/http-dispatcher.d.ts.map +1 -0
  130. package/dist/core/http-dispatcher.js +48 -0
  131. package/dist/core/http-dispatcher.js.map +1 -0
  132. package/dist/core/index.d.ts +9 -8
  133. package/dist/core/index.d.ts.map +1 -1
  134. package/dist/core/index.js +2 -1
  135. package/dist/core/index.js.map +1 -1
  136. package/dist/core/keybindings.d.ts +66 -1
  137. package/dist/core/keybindings.d.ts.map +1 -1
  138. package/dist/core/keybindings.js +56 -1
  139. package/dist/core/keybindings.js.map +1 -1
  140. package/dist/core/model-registry.d.ts +22 -4
  141. package/dist/core/model-registry.d.ts.map +1 -1
  142. package/dist/core/model-registry.js +216 -44
  143. package/dist/core/model-registry.js.map +1 -1
  144. package/dist/core/model-resolver.d.ts +2 -1
  145. package/dist/core/model-resolver.d.ts.map +1 -1
  146. package/dist/core/model-resolver.js +48 -21
  147. package/dist/core/model-resolver.js.map +1 -1
  148. package/dist/core/output-guard.d.ts +1 -0
  149. package/dist/core/output-guard.d.ts.map +1 -1
  150. package/dist/core/output-guard.js +52 -22
  151. package/dist/core/output-guard.js.map +1 -1
  152. package/dist/core/package-manager.d.ts +17 -2
  153. package/dist/core/package-manager.d.ts.map +1 -1
  154. package/dist/core/package-manager.js +363 -121
  155. package/dist/core/package-manager.js.map +1 -1
  156. package/dist/core/project-trust.d.ts +15 -0
  157. package/dist/core/project-trust.d.ts.map +1 -0
  158. package/dist/core/project-trust.js +58 -0
  159. package/dist/core/project-trust.js.map +1 -0
  160. package/dist/core/prompt-templates.d.ts +13 -11
  161. package/dist/core/prompt-templates.d.ts.map +1 -1
  162. package/dist/core/prompt-templates.js +67 -76
  163. package/dist/core/prompt-templates.js.map +1 -1
  164. package/dist/core/provider-attribution.d.ts +4 -0
  165. package/dist/core/provider-attribution.d.ts.map +1 -0
  166. package/dist/core/provider-attribution.js +72 -0
  167. package/dist/core/provider-attribution.js.map +1 -0
  168. package/dist/core/provider-display-names.d.ts +2 -0
  169. package/dist/core/provider-display-names.d.ts.map +1 -0
  170. package/dist/core/provider-display-names.js +36 -0
  171. package/dist/core/provider-display-names.js.map +1 -0
  172. package/dist/core/resolve-config-value.d.ts +9 -1
  173. package/dist/core/resolve-config-value.d.ts.map +1 -1
  174. package/dist/core/resolve-config-value.js +134 -11
  175. package/dist/core/resolve-config-value.js.map +1 -1
  176. package/dist/core/resource-loader.d.ts +34 -14
  177. package/dist/core/resource-loader.d.ts.map +1 -1
  178. package/dist/core/resource-loader.js +165 -76
  179. package/dist/core/resource-loader.js.map +1 -1
  180. package/dist/core/sdk.d.ts +26 -10
  181. package/dist/core/sdk.d.ts.map +1 -1
  182. package/dist/core/sdk.js +45 -16
  183. package/dist/core/sdk.js.map +1 -1
  184. package/dist/core/session-manager.d.ts +11 -12
  185. package/dist/core/session-manager.d.ts.map +1 -1
  186. package/dist/core/session-manager.js +245 -132
  187. package/dist/core/session-manager.js.map +1 -1
  188. package/dist/core/settings-manager.d.ts +52 -5
  189. package/dist/core/settings-manager.d.ts.map +1 -1
  190. package/dist/core/settings-manager.js +202 -38
  191. package/dist/core/settings-manager.js.map +1 -1
  192. package/dist/core/skills.d.ts +10 -10
  193. package/dist/core/skills.d.ts.map +1 -1
  194. package/dist/core/skills.js +13 -35
  195. package/dist/core/skills.js.map +1 -1
  196. package/dist/core/slash-commands.d.ts +1 -1
  197. package/dist/core/slash-commands.d.ts.map +1 -1
  198. package/dist/core/slash-commands.js +7 -4
  199. package/dist/core/slash-commands.js.map +1 -1
  200. package/dist/core/source-info.d.ts +1 -1
  201. package/dist/core/source-info.d.ts.map +1 -1
  202. package/dist/core/source-info.js.map +1 -1
  203. package/dist/core/system-prompt.d.ts +4 -4
  204. package/dist/core/system-prompt.d.ts.map +1 -1
  205. package/dist/core/system-prompt.js +14 -10
  206. package/dist/core/system-prompt.js.map +1 -1
  207. package/dist/core/telemetry.d.ts +3 -0
  208. package/dist/core/telemetry.d.ts.map +1 -0
  209. package/dist/core/telemetry.js +9 -0
  210. package/dist/core/telemetry.js.map +1 -0
  211. package/dist/core/tools/bash.d.ts +11 -16
  212. package/dist/core/tools/bash.d.ts.map +1 -1
  213. package/dist/core/tools/bash.js +162 -177
  214. package/dist/core/tools/bash.js.map +1 -1
  215. package/dist/core/tools/edit-diff.d.ts +3 -1
  216. package/dist/core/tools/edit-diff.d.ts.map +1 -1
  217. package/dist/core/tools/edit-diff.js +11 -3
  218. package/dist/core/tools/edit-diff.js.map +1 -1
  219. package/dist/core/tools/edit.d.ts +22 -24
  220. package/dist/core/tools/edit.d.ts.map +1 -1
  221. package/dist/core/tools/edit.js +199 -111
  222. package/dist/core/tools/edit.js.map +1 -1
  223. package/dist/core/tools/file-mutation-queue.d.ts.map +1 -1
  224. package/dist/core/tools/file-mutation-queue.js +27 -12
  225. package/dist/core/tools/file-mutation-queue.js.map +1 -1
  226. package/dist/core/tools/find.d.ts +7 -18
  227. package/dist/core/tools/find.d.ts.map +1 -1
  228. package/dist/core/tools/find.js +134 -95
  229. package/dist/core/tools/find.js.map +1 -1
  230. package/dist/core/tools/grep.d.ts +11 -30
  231. package/dist/core/tools/grep.d.ts.map +1 -1
  232. package/dist/core/tools/grep.js +23 -12
  233. package/dist/core/tools/grep.js.map +1 -1
  234. package/dist/core/tools/index.d.ts +26 -101
  235. package/dist/core/tools/index.d.ts.map +1 -1
  236. package/dist/core/tools/index.js +78 -52
  237. package/dist/core/tools/index.js.map +1 -1
  238. package/dist/core/tools/ls.d.ts +6 -15
  239. package/dist/core/tools/ls.d.ts.map +1 -1
  240. package/dist/core/tools/ls.js +12 -17
  241. package/dist/core/tools/ls.js.map +1 -1
  242. package/dist/core/tools/output-accumulator.d.ts +52 -0
  243. package/dist/core/tools/output-accumulator.d.ts.map +1 -0
  244. package/dist/core/tools/output-accumulator.js +184 -0
  245. package/dist/core/tools/output-accumulator.js.map +1 -0
  246. package/dist/core/tools/path-utils.d.ts +2 -0
  247. package/dist/core/tools/path-utils.d.ts.map +1 -1
  248. package/dist/core/tools/path-utils.js +40 -22
  249. package/dist/core/tools/path-utils.js.map +1 -1
  250. package/dist/core/tools/read.d.ts +7 -18
  251. package/dist/core/tools/read.d.ts.map +1 -1
  252. package/dist/core/tools/read.js +100 -36
  253. package/dist/core/tools/read.js.map +1 -1
  254. package/dist/core/tools/render-utils.d.ts +5 -2
  255. package/dist/core/tools/render-utils.d.ts.map +1 -1
  256. package/dist/core/tools/render-utils.js +18 -2
  257. package/dist/core/tools/render-utils.js.map +1 -1
  258. package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
  259. package/dist/core/tools/tool-definition-wrapper.js +2 -0
  260. package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
  261. package/dist/core/tools/truncate.d.ts.map +1 -1
  262. package/dist/core/tools/truncate.js +12 -2
  263. package/dist/core/tools/truncate.js.map +1 -1
  264. package/dist/core/tools/write.d.ts +5 -14
  265. package/dist/core/tools/write.d.ts.map +1 -1
  266. package/dist/core/tools/write.js +27 -46
  267. package/dist/core/tools/write.js.map +1 -1
  268. package/dist/core/trust-manager.d.ts +31 -0
  269. package/dist/core/trust-manager.d.ts.map +1 -0
  270. package/dist/core/trust-manager.js +187 -0
  271. package/dist/core/trust-manager.js.map +1 -0
  272. package/dist/index.d.ts +31 -29
  273. package/dist/index.d.ts.map +1 -1
  274. package/dist/index.js +9 -8
  275. package/dist/index.js.map +1 -1
  276. package/dist/main.d.ts +5 -1
  277. package/dist/main.d.ts.map +1 -1
  278. package/dist/main.js +170 -87
  279. package/dist/main.js.map +1 -1
  280. package/dist/migrations.d.ts +2 -2
  281. package/dist/migrations.d.ts.map +1 -1
  282. package/dist/migrations.js +127 -5
  283. package/dist/migrations.js.map +1 -1
  284. package/dist/modes/index.d.ts +5 -5
  285. package/dist/modes/index.d.ts.map +1 -1
  286. package/dist/modes/index.js.map +1 -1
  287. package/dist/modes/interactive/components/assistant-message.d.ts +2 -0
  288. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  289. package/dist/modes/interactive/components/assistant-message.js +14 -0
  290. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  291. package/dist/modes/interactive/components/bash-execution.d.ts +1 -1
  292. package/dist/modes/interactive/components/bash-execution.d.ts.map +1 -1
  293. package/dist/modes/interactive/components/bash-execution.js +3 -3
  294. package/dist/modes/interactive/components/bash-execution.js.map +1 -1
  295. package/dist/modes/interactive/components/bordered-loader.d.ts.map +1 -1
  296. package/dist/modes/interactive/components/bordered-loader.js +3 -0
  297. package/dist/modes/interactive/components/bordered-loader.js.map +1 -1
  298. package/dist/modes/interactive/components/config-selector.d.ts +4 -4
  299. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  300. package/dist/modes/interactive/components/config-selector.js +38 -11
  301. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  302. package/dist/modes/interactive/components/countdown-timer.d.ts +2 -2
  303. package/dist/modes/interactive/components/countdown-timer.d.ts.map +1 -1
  304. package/dist/modes/interactive/components/countdown-timer.js +2 -2
  305. package/dist/modes/interactive/components/countdown-timer.js.map +1 -1
  306. package/dist/modes/interactive/components/custom-editor.d.ts +1 -1
  307. package/dist/modes/interactive/components/custom-editor.d.ts.map +1 -1
  308. package/dist/modes/interactive/components/custom-editor.js.map +1 -1
  309. package/dist/modes/interactive/components/custom-message.d.ts +2 -2
  310. package/dist/modes/interactive/components/custom-message.d.ts.map +1 -1
  311. package/dist/modes/interactive/components/custom-message.js.map +1 -1
  312. package/dist/modes/interactive/components/diff.d.ts.map +1 -1
  313. package/dist/modes/interactive/components/diff.js.map +1 -1
  314. package/dist/modes/interactive/components/earendil-announcement.d.ts.map +1 -1
  315. package/dist/modes/interactive/components/earendil-announcement.js.map +1 -1
  316. package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
  317. package/dist/modes/interactive/components/extension-editor.js +14 -6
  318. package/dist/modes/interactive/components/extension-editor.js.map +1 -1
  319. package/dist/modes/interactive/components/extension-input.d.ts.map +1 -1
  320. package/dist/modes/interactive/components/extension-input.js.map +1 -1
  321. package/dist/modes/interactive/components/extension-selector.d.ts +2 -0
  322. package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
  323. package/dist/modes/interactive/components/extension-selector.js +8 -3
  324. package/dist/modes/interactive/components/extension-selector.js.map +1 -1
  325. package/dist/modes/interactive/components/first-time-setup.d.ts +25 -0
  326. package/dist/modes/interactive/components/first-time-setup.d.ts.map +1 -0
  327. package/dist/modes/interactive/components/first-time-setup.js +103 -0
  328. package/dist/modes/interactive/components/first-time-setup.js.map +1 -0
  329. package/dist/modes/interactive/components/footer.d.ts +2 -1
  330. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  331. package/dist/modes/interactive/components/footer.js +23 -7
  332. package/dist/modes/interactive/components/footer.js.map +1 -1
  333. package/dist/modes/interactive/components/index.d.ts +33 -31
  334. package/dist/modes/interactive/components/index.d.ts.map +1 -1
  335. package/dist/modes/interactive/components/index.js +2 -0
  336. package/dist/modes/interactive/components/index.js.map +1 -1
  337. package/dist/modes/interactive/components/keybinding-hints.d.ts +5 -0
  338. package/dist/modes/interactive/components/keybinding-hints.d.ts.map +1 -1
  339. package/dist/modes/interactive/components/keybinding-hints.js +19 -5
  340. package/dist/modes/interactive/components/keybinding-hints.js.map +1 -1
  341. package/dist/modes/interactive/components/login-dialog.d.ts +12 -2
  342. package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
  343. package/dist/modes/interactive/components/login-dialog.js +46 -11
  344. package/dist/modes/interactive/components/login-dialog.js.map +1 -1
  345. package/dist/modes/interactive/components/model-selector.d.ts +2 -2
  346. package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
  347. package/dist/modes/interactive/components/model-selector.js +8 -5
  348. package/dist/modes/interactive/components/model-selector.js.map +1 -1
  349. package/dist/modes/interactive/components/oauth-selector.d.ts +18 -6
  350. package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
  351. package/dist/modes/interactive/components/oauth-selector.js +93 -25
  352. package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
  353. package/dist/modes/interactive/components/scoped-models-selector.d.ts +5 -12
  354. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
  355. package/dist/modes/interactive/components/scoped-models-selector.js +45 -30
  356. package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
  357. package/dist/modes/interactive/components/session-selector.d.ts +2 -1
  358. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  359. package/dist/modes/interactive/components/session-selector.js +20 -7
  360. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  361. package/dist/modes/interactive/components/settings-selector.d.ts +13 -0
  362. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  363. package/dist/modes/interactive/components/settings-selector.js +113 -4
  364. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  365. package/dist/modes/interactive/components/skill-invocation-message.d.ts +1 -1
  366. package/dist/modes/interactive/components/skill-invocation-message.d.ts.map +1 -1
  367. package/dist/modes/interactive/components/skill-invocation-message.js.map +1 -1
  368. package/dist/modes/interactive/components/thinking-selector.d.ts.map +1 -1
  369. package/dist/modes/interactive/components/thinking-selector.js +1 -1
  370. package/dist/modes/interactive/components/thinking-selector.js.map +1 -1
  371. package/dist/modes/interactive/components/tool-execution.d.ts +6 -1
  372. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  373. package/dist/modes/interactive/components/tool-execution.js +57 -14
  374. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  375. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  376. package/dist/modes/interactive/components/tree-selector.js +18 -9
  377. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  378. package/dist/modes/interactive/components/trust-selector.d.ts +23 -0
  379. package/dist/modes/interactive/components/trust-selector.d.ts.map +1 -0
  380. package/dist/modes/interactive/components/trust-selector.js +91 -0
  381. package/dist/modes/interactive/components/trust-selector.js.map +1 -0
  382. package/dist/modes/interactive/components/user-message-selector.d.ts +2 -2
  383. package/dist/modes/interactive/components/user-message-selector.d.ts.map +1 -1
  384. package/dist/modes/interactive/components/user-message-selector.js +8 -7
  385. package/dist/modes/interactive/components/user-message-selector.js.map +1 -1
  386. package/dist/modes/interactive/components/user-message.d.ts +1 -0
  387. package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
  388. package/dist/modes/interactive/components/user-message.js +8 -7
  389. package/dist/modes/interactive/components/user-message.js.map +1 -1
  390. package/dist/modes/interactive/interactive-mode.d.ts +68 -13
  391. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  392. package/dist/modes/interactive/interactive-mode.js +1100 -319
  393. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  394. package/dist/modes/interactive/theme/dark.json +5 -4
  395. package/dist/modes/interactive/theme/light.json +5 -4
  396. package/dist/modes/interactive/theme/theme.d.ts +22 -3
  397. package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
  398. package/dist/modes/interactive/theme/theme.js +160 -105
  399. package/dist/modes/interactive/theme/theme.js.map +1 -1
  400. package/dist/modes/print-mode.d.ts.map +1 -1
  401. package/dist/modes/print-mode.js +40 -20
  402. package/dist/modes/print-mode.js.map +1 -1
  403. package/dist/modes/rpc/rpc-client.d.ts +11 -1
  404. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  405. package/dist/modes/rpc/rpc-client.js +73 -8
  406. package/dist/modes/rpc/rpc-client.js.map +1 -1
  407. package/dist/modes/rpc/rpc-mode.d.ts +2 -2
  408. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  409. package/dist/modes/rpc/rpc-mode.js +96 -30
  410. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  411. package/dist/modes/rpc/rpc-types.d.ts +16 -4
  412. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  413. package/dist/modes/rpc/rpc-types.js.map +1 -1
  414. package/dist/package-manager-cli.d.ts +6 -2
  415. package/dist/package-manager-cli.d.ts.map +1 -1
  416. package/dist/package-manager-cli.js +396 -21
  417. package/dist/package-manager-cli.js.map +1 -1
  418. package/dist/prompts/commands/map-codebase.md +14 -0
  419. package/dist/utils/ansi.d.ts +2 -0
  420. package/dist/utils/ansi.d.ts.map +1 -0
  421. package/dist/utils/ansi.js +52 -0
  422. package/dist/utils/ansi.js.map +1 -0
  423. package/dist/utils/changelog.d.ts +2 -1
  424. package/dist/utils/changelog.d.ts.map +1 -1
  425. package/dist/utils/changelog.js +78 -0
  426. package/dist/utils/changelog.js.map +1 -1
  427. package/dist/utils/child-process.d.ts +5 -1
  428. package/dist/utils/child-process.d.ts.map +1 -1
  429. package/dist/utils/child-process.js +10 -0
  430. package/dist/utils/child-process.js.map +1 -1
  431. package/dist/utils/clipboard-image.d.ts.map +1 -1
  432. package/dist/utils/clipboard-image.js +2 -2
  433. package/dist/utils/clipboard-image.js.map +1 -1
  434. package/dist/utils/clipboard-native.d.ts +3 -1
  435. package/dist/utils/clipboard-native.d.ts.map +1 -1
  436. package/dist/utils/clipboard-native.js +14 -8
  437. package/dist/utils/clipboard-native.js.map +1 -1
  438. package/dist/utils/clipboard.d.ts.map +1 -1
  439. package/dist/utils/clipboard.js +84 -45
  440. package/dist/utils/clipboard.js.map +1 -1
  441. package/dist/utils/deprecation.d.ts +4 -0
  442. package/dist/utils/deprecation.d.ts.map +1 -0
  443. package/dist/utils/deprecation.js +13 -0
  444. package/dist/utils/deprecation.js.map +1 -0
  445. package/dist/utils/exif-orientation.d.ts +1 -1
  446. package/dist/utils/exif-orientation.d.ts.map +1 -1
  447. package/dist/utils/exif-orientation.js.map +1 -1
  448. package/dist/utils/fs-watch.d.ts +5 -0
  449. package/dist/utils/fs-watch.d.ts.map +1 -0
  450. package/dist/utils/fs-watch.js +25 -0
  451. package/dist/utils/fs-watch.js.map +1 -0
  452. package/dist/utils/git.d.ts.map +1 -1
  453. package/dist/utils/git.js +54 -22
  454. package/dist/utils/git.js.map +1 -1
  455. package/dist/utils/html.d.ts +7 -0
  456. package/dist/utils/html.d.ts.map +1 -0
  457. package/dist/utils/html.js +40 -0
  458. package/dist/utils/html.js.map +1 -0
  459. package/dist/utils/image-convert.d.ts.map +1 -1
  460. package/dist/utils/image-convert.js.map +1 -1
  461. package/dist/utils/image-resize-core.d.ts +30 -0
  462. package/dist/utils/image-resize-core.d.ts.map +1 -0
  463. package/dist/utils/image-resize-core.js +124 -0
  464. package/dist/utils/image-resize-core.js.map +1 -0
  465. package/dist/utils/image-resize-worker.d.ts +2 -0
  466. package/dist/utils/image-resize-worker.d.ts.map +1 -0
  467. package/dist/utils/image-resize-worker.js +31 -0
  468. package/dist/utils/image-resize-worker.js.map +1 -0
  469. package/dist/utils/image-resize.d.ts +7 -27
  470. package/dist/utils/image-resize.d.ts.map +1 -1
  471. package/dist/utils/image-resize.js +75 -115
  472. package/dist/utils/image-resize.js.map +1 -1
  473. package/dist/utils/json.d.ts +3 -0
  474. package/dist/utils/json.d.ts.map +1 -0
  475. package/dist/utils/json.js +7 -0
  476. package/dist/utils/json.js.map +1 -0
  477. package/dist/utils/mime.d.ts +1 -0
  478. package/dist/utils/mime.d.ts.map +1 -1
  479. package/dist/utils/mime.js +59 -16
  480. package/dist/utils/mime.js.map +1 -1
  481. package/dist/utils/open-browser.d.ts +9 -0
  482. package/dist/utils/open-browser.d.ts.map +1 -0
  483. package/dist/utils/open-browser.js +22 -0
  484. package/dist/utils/open-browser.js.map +1 -0
  485. package/dist/utils/paths.d.ts +25 -1
  486. package/dist/utils/paths.d.ts.map +1 -1
  487. package/dist/utils/paths.js +75 -2
  488. package/dist/utils/paths.js.map +1 -1
  489. package/dist/utils/pi-user-agent.d.ts +2 -0
  490. package/dist/utils/pi-user-agent.d.ts.map +1 -0
  491. package/dist/utils/pi-user-agent.js +5 -0
  492. package/dist/utils/pi-user-agent.js.map +1 -0
  493. package/dist/utils/shell.d.ts +10 -6
  494. package/dist/utils/shell.d.ts.map +1 -1
  495. package/dist/utils/shell.js +35 -26
  496. package/dist/utils/shell.js.map +1 -1
  497. package/dist/utils/syntax-highlight.d.ts +12 -0
  498. package/dist/utils/syntax-highlight.d.ts.map +1 -0
  499. package/dist/utils/syntax-highlight.js +118 -0
  500. package/dist/utils/syntax-highlight.js.map +1 -0
  501. package/dist/utils/tools-manager.d.ts.map +1 -1
  502. package/dist/utils/tools-manager.js +86 -10
  503. package/dist/utils/tools-manager.js.map +1 -1
  504. package/dist/utils/version-check.d.ts +15 -0
  505. package/dist/utils/version-check.d.ts.map +1 -0
  506. package/dist/utils/version-check.js +82 -0
  507. package/dist/utils/version-check.js.map +1 -0
  508. package/dist/utils/windows-self-update.d.ts +3 -0
  509. package/dist/utils/windows-self-update.d.ts.map +1 -0
  510. package/dist/utils/windows-self-update.js +77 -0
  511. package/dist/utils/windows-self-update.js.map +1 -0
  512. package/docs/compaction.md +12 -12
  513. package/docs/containerization.md +111 -0
  514. package/docs/custom-provider.md +187 -47
  515. package/docs/development.md +5 -5
  516. package/docs/docs.json +156 -0
  517. package/docs/extensions.md +465 -71
  518. package/docs/index.md +82 -0
  519. package/docs/json.md +4 -4
  520. package/docs/keybindings.md +23 -1
  521. package/docs/models.md +119 -17
  522. package/docs/packages.md +17 -9
  523. package/docs/prompt-templates.md +30 -2
  524. package/docs/providers.md +83 -22
  525. package/docs/quickstart.md +165 -0
  526. package/docs/rpc.md +41 -10
  527. package/docs/sdk.md +68 -50
  528. package/docs/security.md +55 -0
  529. package/docs/{session.md → session-format.md} +11 -11
  530. package/docs/sessions.md +145 -0
  531. package/docs/settings.md +61 -11
  532. package/docs/skills.md +16 -17
  533. package/docs/terminal-setup.md +44 -2
  534. package/docs/termux.md +4 -4
  535. package/docs/themes.md +3 -3
  536. package/docs/tmux.md +4 -2
  537. package/docs/tui.md +44 -4
  538. package/docs/usage.md +305 -0
  539. package/examples/extensions/border-status-editor.ts +145 -0
  540. package/examples/extensions/built-in-tool-renderer.ts +3 -0
  541. package/examples/extensions/custom-header.ts +1 -1
  542. package/examples/extensions/custom-provider-anthropic/index.ts +1 -1
  543. package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
  544. package/examples/extensions/custom-provider-anthropic/package.json +2 -2
  545. package/examples/extensions/custom-provider-gitlab-duo/index.ts +55 -4
  546. package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  547. package/examples/extensions/custom-provider-gitlab-duo/test.ts +1 -1
  548. package/examples/extensions/doom-overlay/doom-component.ts +2 -2
  549. package/examples/extensions/doom-overlay/index.ts +1 -1
  550. package/examples/extensions/dynamic-resources/dynamic.json +1 -1
  551. package/examples/extensions/dynamic-tools.ts +2 -2
  552. package/examples/extensions/git-merge-and-resolve.ts +115 -0
  553. package/examples/extensions/github-issue-autocomplete.ts +185 -0
  554. package/examples/extensions/gondolin/index.ts +531 -0
  555. package/examples/extensions/gondolin/package-lock.json +185 -0
  556. package/examples/extensions/gondolin/package.json +19 -0
  557. package/examples/extensions/handoff.ts +50 -12
  558. package/examples/extensions/input-transform-streaming.ts +39 -0
  559. package/examples/extensions/interactive-shell.ts +1 -1
  560. package/examples/extensions/notify.ts +2 -9
  561. package/examples/extensions/overlay-qa-tests.ts +240 -138
  562. package/examples/extensions/overlay-test.ts +7 -4
  563. package/examples/extensions/plan-mode/utils.ts +1 -1
  564. package/examples/extensions/preset.ts +36 -3
  565. package/examples/extensions/project-trust.ts +64 -0
  566. package/examples/extensions/prompt-customizer.ts +97 -0
  567. package/examples/extensions/provider-payload.ts +4 -0
  568. package/examples/extensions/qna.ts +1 -1
  569. package/examples/extensions/question.ts +2 -2
  570. package/examples/extensions/questionnaire.ts +2 -2
  571. package/examples/extensions/reload-runtime.ts +1 -1
  572. package/examples/extensions/sandbox/index.ts +4 -4
  573. package/examples/extensions/sandbox/package-lock.json +5 -5
  574. package/examples/extensions/sandbox/package.json +2 -2
  575. package/examples/extensions/shutdown-command.ts +1 -1
  576. package/examples/extensions/snake.ts +1 -1
  577. package/examples/extensions/space-invaders.ts +1 -1
  578. package/examples/extensions/structured-output.ts +65 -0
  579. package/examples/extensions/subagent/index.ts +51 -28
  580. package/examples/extensions/summarize.ts +1 -1
  581. package/examples/extensions/tic-tac-toe.ts +1008 -0
  582. package/examples/extensions/titlebar-spinner.ts +2 -2
  583. package/examples/extensions/todo.ts +2 -2
  584. package/examples/extensions/tool-override.ts +1 -1
  585. package/examples/extensions/tools.ts +5 -0
  586. package/examples/extensions/truncated-tool.ts +1 -1
  587. package/examples/extensions/with-deps/index.ts +1 -1
  588. package/examples/extensions/with-deps/package-lock.json +2 -2
  589. package/examples/extensions/with-deps/package.json +3 -3
  590. package/examples/extensions/working-indicator.ts +123 -0
  591. package/examples/extensions/working-message-test.ts +25 -0
  592. package/examples/sdk/01-minimal.ts +14 -10
  593. package/examples/sdk/02-custom-model.ts +12 -8
  594. package/examples/sdk/03-custom-prompt.ts +32 -17
  595. package/examples/sdk/04-skills.ts +5 -2
  596. package/examples/sdk/05-tools.ts +23 -31
  597. package/examples/sdk/06-extensions.ts +14 -8
  598. package/examples/sdk/07-context-files.ts +5 -3
  599. package/examples/sdk/08-prompt-templates.ts +5 -2
  600. package/examples/sdk/09-api-keys-and-oauth.ts +8 -4
  601. package/examples/sdk/10-settings.ts +8 -6
  602. package/examples/sdk/11-sessions.ts +4 -0
  603. package/examples/sdk/12-full-control.ts +13 -17
  604. package/package.json +13 -6
  605. package/prompts/commands/map-codebase.md +14 -0
package/docs/skills.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.
6
6
 
7
- Pi implements the [Agent Skills standard](https://agentskills.io/specification), warning about violations but remaining lenient.
7
+ Pi implements the [Agent Skills standard](https://agentskills.io/specification), warning about most violations but remaining lenient. Pi allows skill names to differ from their parent directory even though the standard disallows it; that rule is suboptimal for shared skill directories used across multiple agent harnesses.
8
8
 
9
9
  ## Table of Contents
10
10
 
@@ -26,7 +26,7 @@ Pi loads skills from:
26
26
  - Global:
27
27
  - `~/.pi/agent/skills/`
28
28
  - `~/.agents/skills/`
29
- - Project:
29
+ - Project (only after the project is trusted):
30
30
  - `.pi/skills/`
31
31
  - `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
32
32
  - Packages: `skills/` directories or `pi.skills` entries in `package.json`
@@ -106,7 +106,7 @@ my-skill/
106
106
 
107
107
  ### SKILL.md Format
108
108
 
109
- ```markdown
109
+ ````markdown
110
110
  ---
111
111
  name: my-skill
112
112
  description: What this skill does and when to use it. Be specific.
@@ -117,16 +117,16 @@ description: What this skill does and when to use it. Be specific.
117
117
  ## Setup
118
118
 
119
119
  Run once before first use:
120
- \`\`\`bash
120
+ ```bash
121
121
  cd /path/to/skill && npm install
122
- \`\`\`
122
+ ```
123
123
 
124
124
  ## Usage
125
125
 
126
- \`\`\`bash
126
+ ```bash
127
127
  ./scripts/process.sh <input>
128
- \`\`\`
129
128
  ```
129
+ ````
130
130
 
131
131
  Use relative paths from the skill directory:
132
132
 
@@ -140,7 +140,7 @@ Per the [Agent Skills specification](https://agentskills.io/specification#frontm
140
140
 
141
141
  | Field | Required | Description |
142
142
  |-------|----------|-------------|
143
- | `name` | Yes | Max 64 chars. Lowercase a-z, 0-9, hyphens. Must match parent directory. |
143
+ | `name` | Yes | Max 64 chars. Lowercase a-z, 0-9, hyphens. Unlike the standard, Pi does not require this to match the parent directory because that standard requirement is suboptimal for shared skill directories. |
144
144
  | `description` | Yes | Max 1024 chars. What the skill does and when to use it. |
145
145
  | `license` | No | License name or reference to bundled file. |
146
146
  | `compatibility` | No | Max 500 chars. Environment requirements. |
@@ -154,7 +154,7 @@ Per the [Agent Skills specification](https://agentskills.io/specification#frontm
154
154
  - Lowercase letters, numbers, hyphens only
155
155
  - No leading/trailing hyphens
156
156
  - No consecutive hyphens
157
- - Must match parent directory name
157
+ Pi does not require the name to match the parent directory. The Agent Skills standard does, but that requirement is suboptimal for shared skill directories used by multiple tools.
158
158
 
159
159
  Valid: `pdf-processing`, `data-analysis`, `code-review`
160
160
  Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
@@ -177,7 +177,6 @@ description: Helps with PDFs.
177
177
 
178
178
  Pi validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill:
179
179
 
180
- - Name doesn't match parent directory
181
180
  - Name exceeds 64 characters or contains invalid characters
182
181
  - Name starts/ends with hyphen or has consecutive hyphens
183
182
  - Description exceeds 1024 characters
@@ -198,7 +197,7 @@ brave-search/
198
197
  ```
199
198
 
200
199
  **SKILL.md:**
201
- ```markdown
200
+ ````markdown
202
201
  ---
203
202
  name: brave-search
204
203
  description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
@@ -208,23 +207,23 @@ description: Web search and content extraction via Brave Search API. Use for sea
208
207
 
209
208
  ## Setup
210
209
 
211
- \`\`\`bash
210
+ ```bash
212
211
  cd /path/to/brave-search && npm install
213
- \`\`\`
212
+ ```
214
213
 
215
214
  ## Search
216
215
 
217
- \`\`\`bash
216
+ ```bash
218
217
  ./search.js "query" # Basic search
219
218
  ./search.js "query" --content # Include page content
220
- \`\`\`
219
+ ```
221
220
 
222
221
  ## Extract Page Content
223
222
 
224
- \`\`\`bash
223
+ ```bash
225
224
  ./content.js https://example.com
226
- \`\`\`
227
225
  ```
226
+ ````
228
227
 
229
228
  ## Skill Repositories
230
229
 
@@ -6,6 +6,12 @@ Pi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-p
6
6
 
7
7
  Work out of the box.
8
8
 
9
+ ## Apple Terminal
10
+
11
+ Pi enables enhanced key reporting when available. If Terminal.app still sends plain Return for `Shift+Enter`, pi uses a local macOS modifier fallback to treat that Return as `Shift+Enter`.
12
+
13
+ This fallback only works when pi runs on the same Mac as Terminal.app. It cannot detect the local keyboard over remote SSH.
14
+
9
15
  ## Ghostty
10
16
 
11
17
  Add to your Ghostty config (`~/Library/Application Support/com.mitchellh.ghostty/config` on macOS, `~/.config/ghostty/config` on Linux):
@@ -34,7 +40,7 @@ If you want `Shift+Enter` to keep working in tmux via that remap, add `ctrl+j` t
34
40
 
35
41
  ## WezTerm
36
42
 
37
- Create `~/.wezterm.lua`:
43
+ WezTerm usually works out of the box for `Shift+Enter` via xterm modifyOtherKeys. To use the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:
38
44
 
39
45
  ```lua
40
46
  local wezterm = require 'wezterm'
@@ -43,14 +49,50 @@ config.enable_kitty_keyboard = true
43
49
  return config
44
50
  ```
45
51
 
52
+ On macOS, WezTerm binds `Option+Enter` to fullscreen by default. To use `Option+Enter` for pi follow-up queueing, add this key override:
53
+
54
+ ```lua
55
+ local wezterm = require 'wezterm'
56
+ local config = wezterm.config_builder()
57
+ config.keys = {
58
+ {
59
+ key = 'Enter',
60
+ mods = 'ALT',
61
+ action = wezterm.action.SendString('\x1b[13;3u'),
62
+ },
63
+ }
64
+ return config
65
+ ```
66
+
67
+ If you already have a `config.keys` table, add the entry to it.
68
+
69
+ On WSL, WezTerm may require a visible hardware cursor for IME candidate window positioning. If CJK IME candidates do not follow the text cursor, set `PI_HARDWARE_CURSOR=1` before running pi or set `showHardwareCursor` to `true` in settings.
70
+
71
+ ## Alacritty
72
+
73
+ Alacritty usually works out of the box for `Shift+Enter`. On macOS, `Option+Enter` may arrive as plain `Enter`. To use `Option+Enter` for pi follow-up queueing, add to `~/.config/alacritty/alacritty.toml`:
74
+
75
+ ```toml
76
+ [[keyboard.bindings]]
77
+ key = "Enter"
78
+ mods = "Alt"
79
+ chars = "\u001b[13;3u"
80
+ ```
81
+
82
+ Restart Alacritty after changing the config.
83
+
46
84
  ## VS Code (Integrated Terminal)
47
85
 
86
+ VS Code 1.109.5 and newer enable Kitty keyboard protocol in the integrated terminal by default, so `Shift+Enter` should work out of the box.
87
+
88
+ VS Code versions older than 1.109.5 need an explicit terminal keybinding for `Shift+Enter`.
89
+
48
90
  `keybindings.json` locations:
49
91
  - macOS: `~/Library/Application Support/Code/User/keybindings.json`
50
92
  - Linux: `~/.config/Code/User/keybindings.json`
51
93
  - Windows: `%APPDATA%\\Code\\User\\keybindings.json`
52
94
 
53
- Add to `keybindings.json` to enable `Shift+Enter` for multi-line input:
95
+ Add to `keybindings.json`:
54
96
 
55
97
  ```json
56
98
  {
package/docs/termux.md CHANGED
@@ -17,7 +17,7 @@ pkg update && pkg upgrade
17
17
  pkg install nodejs termux-api git
18
18
 
19
19
  # Install pi
20
- npm install -g @draht/coding-agent
20
+ npm install -g --ignore-scripts @draht/coding-agent
21
21
 
22
22
  # Create config directory
23
23
  mkdir -p ~/.pi/agent
@@ -36,7 +36,7 @@ Image clipboard is not supported on Termux (the `ctrl+v` image paste feature wil
36
36
 
37
37
  Create `~/.pi/agent/AGENTS.md` to help the agent understand the Termux environment:
38
38
 
39
- ```markdown
39
+ ````markdown
40
40
  # Agent Environment: Termux on Android
41
41
 
42
42
  ## Location
@@ -53,7 +53,7 @@ termux-open-url "https://example.com"
53
53
  ## Opening Files
54
54
  ```bash
55
55
  termux-open file.pdf # Opens with default app
56
- termux-open -c image.jpg # Choose app
56
+ termux-open --chooser image.jpg # Choose app
57
57
  ```
58
58
 
59
59
  ## Clipboard
@@ -91,7 +91,7 @@ termux-camera-photo out.jpg # Take photo
91
91
  - Termux:API app must be installed for `termux-*` commands
92
92
  - Use `pkg install termux-api` for the command-line tools
93
93
  - Storage permission needed for `/storage/emulated/0` access
94
- ```
94
+ ````
95
95
 
96
96
  ## Limitations
97
97
 
package/docs/themes.md CHANGED
@@ -20,7 +20,7 @@ Pi loads themes from:
20
20
 
21
21
  - Built-in: `dark`, `light`
22
22
  - Global: `~/.pi/agent/themes/*.json`
23
- - Project: `.pi/themes/*.json`
23
+ - Project: `.pi/themes/*.json` (only after the project is trusted)
24
24
  - Packages: `themes/` directories or `pi.themes` entries in `package.json`
25
25
  - Settings: `themes` array with files or directories
26
26
  - CLI: `--theme <path>` (repeatable)
@@ -52,7 +52,7 @@ vim ~/.pi/agent/themes/my-theme.json
52
52
 
53
53
  ```json
54
54
  {
55
- "$schema": "https://raw.githubusercontent.com/draht-dev/draht/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
55
+ "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
56
56
  "name": "my-theme",
57
57
  "vars": {
58
58
  "primary": "#00aaff",
@@ -122,7 +122,7 @@ vim ~/.pi/agent/themes/my-theme.json
122
122
 
123
123
  ```json
124
124
  {
125
- "$schema": "https://raw.githubusercontent.com/draht-dev/draht/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
125
+ "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
126
126
  "name": "my-theme",
127
127
  "vars": {
128
128
  "blue": "#0066cc",
package/docs/tmux.md CHANGED
@@ -18,7 +18,7 @@ tmux kill-server
18
18
  tmux
19
19
  ```
20
20
 
21
- Pi requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration.
21
+ Pi requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration. The `extended-keys-format` option requires tmux 3.5 or later.
22
22
 
23
23
  ## Why `csi-u` Is Recommended
24
24
 
@@ -57,5 +57,7 @@ This affects the default keybindings (`Enter` to submit, `Shift+Enter` for newli
57
57
 
58
58
  ## Requirements
59
59
 
60
- - tmux 3.2 or later (run `tmux -V` to check)
60
+ - tmux 3.5 or later for `extended-keys-format csi-u` (run `tmux -V` to check)
61
61
  - A terminal emulator that supports extended keys (Ghostty, Kitty, iTerm2, WezTerm, Windows Terminal)
62
+
63
+ With tmux 3.2 through 3.4, omit `extended-keys-format csi-u`; Pi still supports tmux's default xterm `modifyOtherKeys` format.
package/docs/tui.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  Extensions and custom tools can render custom TUI components for interactive user interfaces. This page covers the component system and available building blocks.
6
6
 
7
- **Source:** [`@draht/tui`](https://github.com/draht-dev/draht/tree/main/packages/tui)
7
+ **Source:** [`@draht/tui`](https://github.com/earendil-works/pi-mono/tree/main/packages/tui)
8
8
 
9
9
  ## Component Interface
10
10
 
@@ -50,9 +50,9 @@ When a `Focusable` component has focus, TUI:
50
50
  1. Sets `focused = true` on the component
51
51
  2. Scans rendered output for `CURSOR_MARKER` (a zero-width APC escape sequence)
52
52
  3. Positions the hardware terminal cursor at that location
53
- 4. Shows the hardware cursor
53
+ 4. Shows the hardware cursor only when `showHardwareCursor` is enabled
54
54
 
55
- This enables IME candidate windows to appear at the correct position for CJK input methods. The `Editor` and `Input` built-in components already implement this interface.
55
+ The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with `showHardwareCursor`, `setShowHardwareCursor(true)`, or `PI_HARDWARE_CURSOR=1`. The `Editor` and `Input` built-in components already implement this interface.
56
56
 
57
57
  ### Container Components with Embedded Inputs
58
58
 
@@ -145,8 +145,11 @@ const result = await ctx.ui.custom<string | null>(
145
145
  // Responsive: hide on narrow terminals
146
146
  visible: (termWidth, termHeight) => termWidth >= 80,
147
147
  },
148
- // Get handle for programmatic visibility control
148
+ // Get handle for programmatic focus and visibility control
149
149
  onHandle: (handle) => {
150
+ // handle.focus() - focus this overlay and bring it to the visual front
151
+ // handle.unfocus() - release input to normal fallback
152
+ // handle.unfocus({ target }) - release input to a specific component or null
150
153
  // handle.setHidden(true/false) - toggle visibility
151
154
  // handle.hide() - permanently remove
152
155
  },
@@ -154,6 +157,12 @@ const result = await ctx.ui.custom<string | null>(
154
157
  );
155
158
  ```
156
159
 
160
+ ### Overlay Focus
161
+
162
+ A focused visible overlay keeps input ownership across temporary non-overlay UI. If an overlay opens another `ctx.ui.custom()` component without `{ overlay: true }`, that replacement UI receives input while it is active; when it closes, the focused overlay can reclaim input.
163
+
164
+ Use `handle.unfocus()` when a visible overlay should stop owning input and let TUI fall back to another visible capturing overlay or the previous focus target. Use `handle.unfocus({ target })` when a specific component should receive input while the overlay stays visible. Passing `{ target: null }` intentionally leaves no focused component until focus is set again.
165
+
157
166
  ### Overlay Lifecycle
158
167
 
159
168
  Overlay components are disposed when closed. Don't reuse references - create fresh instances:
@@ -735,6 +744,36 @@ ctx.ui.setStatus("my-ext", undefined);
735
744
 
736
745
  **Examples:** [status-line.ts](../examples/extensions/status-line.ts), [plan-mode.ts](../examples/extensions/plan-mode.ts), [preset.ts](../examples/extensions/preset.ts)
737
746
 
747
+ ### Pattern 4b: Working Indicator Customization
748
+
749
+ Customize the inline working indicator shown while pi is streaming a response.
750
+
751
+ ```typescript
752
+ // Static indicator
753
+ ctx.ui.setWorkingIndicator({ frames: [ctx.ui.theme.fg("accent", "●")] });
754
+
755
+ // Custom animated indicator
756
+ ctx.ui.setWorkingIndicator({
757
+ frames: [
758
+ ctx.ui.theme.fg("dim", "·"),
759
+ ctx.ui.theme.fg("muted", "•"),
760
+ ctx.ui.theme.fg("accent", "●"),
761
+ ctx.ui.theme.fg("muted", "•"),
762
+ ],
763
+ intervalMs: 120,
764
+ });
765
+
766
+ // Hide the indicator entirely
767
+ ctx.ui.setWorkingIndicator({ frames: [] });
768
+
769
+ // Restore pi's default spinner
770
+ ctx.ui.setWorkingIndicator();
771
+ ```
772
+
773
+ This only affects the normal streaming working indicator. Compaction and retry loaders keep their built-in styling. Custom frames are rendered verbatim, so extensions must add their own colors when needed.
774
+
775
+ **Examples:** [working-indicator.ts](../examples/extensions/working-indicator.ts)
776
+
738
777
  ### Pattern 5: Widgets Above/Below Editor
739
778
 
740
779
  Show persistent content above or below the input editor. Good for todo lists, progress.
@@ -881,6 +920,7 @@ export default function (pi: ExtensionAPI) {
881
920
  - **Async with cancel**: [examples/extensions/qna.ts](../examples/extensions/qna.ts) - BorderedLoader for LLM calls
882
921
  - **Settings toggles**: [examples/extensions/tools.ts](../examples/extensions/tools.ts) - SettingsList for tool enable/disable
883
922
  - **Status indicators**: [examples/extensions/plan-mode.ts](../examples/extensions/plan-mode.ts) - setStatus and setWidget
923
+ - **Working indicator**: [examples/extensions/working-indicator.ts](../examples/extensions/working-indicator.ts) - setWorkingIndicator
884
924
  - **Custom footer**: [examples/extensions/custom-footer.ts](../examples/extensions/custom-footer.ts) - setFooter with stats
885
925
  - **Custom editor**: [examples/extensions/modal-editor.ts](../examples/extensions/modal-editor.ts) - Vim-like modal editing
886
926
  - **Snake game**: [examples/extensions/snake.ts](../examples/extensions/snake.ts) - Full game with keyboard input, game loop
package/docs/usage.md ADDED
@@ -0,0 +1,305 @@
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 --name "my task" # Set session display name at startup
80
+ pi --session <path|id> # Use a specific session file or session ID
81
+ pi --fork <path|id> # Fork a session into a new session file
82
+ ```
83
+
84
+ Useful session commands:
85
+
86
+ - `/session` shows the current session file and ID.
87
+ - `/tree` navigates the in-file session tree and can summarize abandoned branches.
88
+ - `/fork` creates a new session from an earlier user message.
89
+ - `/clone` duplicates the current active branch into a new session file.
90
+ - `/compact` summarizes older messages to free context.
91
+
92
+ See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
93
+
94
+ ## Context Files
95
+
96
+ Pi loads `AGENTS.md` or `CLAUDE.md` at startup from:
97
+
98
+ - `~/.pi/agent/AGENTS.md` for global instructions
99
+ - parent directories, walking up from the current working directory
100
+ - the current directory
101
+
102
+ Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
103
+
104
+ ### System Prompt Files
105
+
106
+ Replace the default system prompt with:
107
+
108
+ - `.pi/SYSTEM.md` for a project
109
+ - `~/.pi/agent/SYSTEM.md` globally
110
+
111
+ Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
112
+
113
+ ### Project Trust
114
+
115
+ On interactive startup, pi asks before trusting a project folder that contains project-local extensions or settings and has no saved decision for the folder or a parent folder in `~/.pi/agent/trust.json`. Trusting a project allows pi to load `.pi/settings.json` and `.pi` resources, install missing project packages, and execute project extensions.
116
+
117
+ Before the trust decision, pi loads only context files, user/global extensions, and CLI `-e` extensions so they can handle the `project_trust` event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted. This split also applies when switching to a session from a different cwd whose trust has not been resolved in the current process.
118
+
119
+ Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore trust-gated project inputs, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
120
+
121
+ If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.pi/agent/settings.json`, or change it with `/settings`.
122
+
123
+ `pi config` and package commands use the same project trust flow. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
124
+
125
+ Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.pi/agent/trust.json` only; the current session is not reloaded, so restart pi for changes to take effect.
126
+
127
+
128
+ ## Exporting and Sharing Sessions
129
+
130
+ Use `/export [file]` to write a session to HTML.
131
+
132
+ Use `/share` to upload a private GitHub gist with a shareable HTML link.
133
+
134
+ 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.
135
+
136
+ ## CLI Reference
137
+
138
+ ```bash
139
+ pi [options] [@files...] [messages...]
140
+ ```
141
+
142
+ ### Package Commands
143
+
144
+ ```bash
145
+ pi install <source> [-l] # Install package, -l for project-local
146
+ pi remove <source> [-l] # Remove package
147
+ pi uninstall <source> [-l] # Alias for remove
148
+ pi update [source|self|pi] # Update pi and packages; reconcile pinned git refs
149
+ pi update --extensions # Update packages only; reconcile pinned git refs
150
+ pi update --self # Update pi only
151
+ pi update --extension <src> # Update one package
152
+ pi list # List installed packages
153
+ pi config # Enable/disable package resources
154
+ ```
155
+
156
+ These commands manage pi packages, not the pi CLI installation. To uninstall pi itself, see [Quickstart](quickstart.md#uninstall). `pi config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command.
157
+
158
+ See [Pi Packages](packages.md) for package sources and security notes.
159
+
160
+ ### Modes
161
+
162
+ | Flag | Description |
163
+ |------|-------------|
164
+ | default | Interactive mode |
165
+ | `-p`, `--print` | Print response and exit |
166
+ | `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
167
+ | `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
168
+ | `--export <in> [out]` | Export a session to HTML |
169
+
170
+ In print mode, pi also reads piped stdin and merges it into the initial prompt:
171
+
172
+ ```bash
173
+ cat README.md | pi -p "Summarize this text"
174
+ ```
175
+
176
+ ### Model Options
177
+
178
+ | Option | Description |
179
+ |--------|-------------|
180
+ | `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
181
+ | `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
182
+ | `--api-key <key>` | API key, overriding environment variables |
183
+ | `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
184
+ | `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
185
+ | `--list-models [search]` | List available models |
186
+
187
+ ### Session Options
188
+
189
+ | Option | Description |
190
+ |--------|-------------|
191
+ | `-c`, `--continue` | Continue the most recent session |
192
+ | `-r`, `--resume` | Browse and select a session |
193
+ | `--session <path\|id>` | Use a specific session file or partial UUID |
194
+ | `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
195
+ | `--session-dir <dir>` | Custom session storage directory |
196
+ | `--no-session` | Ephemeral mode; do not save |
197
+ | `--name <name>`, `-n <name>` | Set session display name at startup |
198
+
199
+ ### Tool Options
200
+
201
+ | Option | Description |
202
+ |--------|-------------|
203
+ | `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
204
+ | `--exclude-tools <list>`, `-xt <list>` | Disable specific built-in, extension, and custom tools |
205
+ | `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
206
+ | `--no-tools`, `-nt` | Disable all tools |
207
+
208
+ Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
209
+
210
+ ### Resource Options
211
+
212
+ | Option | Description |
213
+ |--------|-------------|
214
+ | `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
215
+ | `--no-extensions` | Disable extension discovery |
216
+ | `--skill <path>` | Load a skill; repeatable |
217
+ | `--no-skills` | Disable skill discovery |
218
+ | `--prompt-template <path>` | Load a prompt template; repeatable |
219
+ | `--no-prompt-templates` | Disable prompt template discovery |
220
+ | `--theme <path>` | Load a theme; repeatable |
221
+ | `--no-themes` | Disable theme discovery |
222
+ | `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
223
+
224
+ Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
225
+
226
+ ```bash
227
+ pi --no-extensions -e ./my-extension.ts
228
+ ```
229
+
230
+ ### Other Options
231
+
232
+ | Option | Description |
233
+ |--------|-------------|
234
+ | `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
235
+ | `--append-system-prompt <text>` | Append to system prompt |
236
+ | `--verbose` | Force verbose startup |
237
+ | `-a`, `--approve` | Trust project-local files for this run |
238
+ | `-na`, `--no-approve` | Ignore project-local files for this run |
239
+ | `-h`, `--help` | Show help |
240
+ | `-v`, `--version` | Show version |
241
+
242
+ ### File Arguments
243
+
244
+ Prefix files with `@` to include them in the message:
245
+
246
+ ```bash
247
+ pi @prompt.md "Answer this"
248
+ pi -p @screenshot.png "What's in this image?"
249
+ pi @code.ts @test.ts "Review these files"
250
+ ```
251
+
252
+ ### Examples
253
+
254
+ ```bash
255
+ # Interactive with initial prompt
256
+ pi "List all .ts files in src/"
257
+
258
+ # Non-interactive
259
+ pi -p "Summarize this codebase"
260
+
261
+ # Non-interactive with piped stdin
262
+ cat README.md | pi -p "Summarize this text"
263
+
264
+ # Named one-shot session
265
+ pi --name "release audit" -p "Audit this repository"
266
+
267
+ # Different model
268
+ pi --provider openai --model gpt-4o "Help me refactor"
269
+
270
+ # Model with provider prefix
271
+ pi --model openai/gpt-4o "Help me refactor"
272
+
273
+ # Model with thinking level shorthand
274
+ pi --model sonnet:high "Solve this complex problem"
275
+
276
+ # Limit model cycling
277
+ pi --models "claude-*,gpt-4o"
278
+
279
+ # Read-only mode
280
+ pi --tools read,grep,find,ls -p "Review the code"
281
+
282
+ # Disable one extension or built-in tool while keeping the rest available
283
+ pi --exclude-tools ask_question
284
+ ```
285
+
286
+ ### Environment Variables
287
+
288
+ | Variable | Description |
289
+ |----------|-------------|
290
+ | `PI_CODING_AGENT_DIR` | Override config directory; default is `~/.pi/agent` |
291
+ | `PI_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
292
+ | `PI_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
293
+ | `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
294
+ | `PI_SKIP_VERSION_CHECK` | Skip the Pi version update check at startup. This prevents the `pi.dev` latest-version request |
295
+ | `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
296
+ | `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
297
+ | `VISUAL`, `EDITOR` | External editor for Ctrl+G |
298
+
299
+ ## Design Principles
300
+
301
+ Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
302
+
303
+ 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.
304
+
305
+ For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).