@narumitw/pi-starship 0.54.0 → 0.55.1

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 (33) hide show
  1. package/README.md +51 -660
  2. package/dist/chunks/{chunk-OZDBEKV2.js → chunk-UX6PBXVK.js} +2 -2
  3. package/dist/chunks/{chunk-OZDBEKV2.js.map → chunk-UX6PBXVK.js.map} +1 -1
  4. package/dist/chunks/{cloud-GEBXIN43.js → cloud-BKHYWCTA.js} +3 -3
  5. package/dist/chunks/cloud-BKHYWCTA.js.map +7 -0
  6. package/dist/chunks/{commands-Z3V7LRUY.js → commands-53ZO2JUK.js} +2 -2
  7. package/dist/chunks/{development-TOXV7LWE.js → development-BERD42HW.js} +2 -2
  8. package/dist/chunks/{development-TOXV7LWE.js.map → development-BERD42HW.js.map} +2 -2
  9. package/dist/chunks/{execution-QDYHQKST.js → execution-42JTEY3N.js} +2 -2
  10. package/dist/chunks/{execution-QDYHQKST.js.map → execution-42JTEY3N.js.map} +2 -2
  11. package/dist/chunks/{languages-QR3XPRVQ.js → languages-RMP6DW7H.js} +2 -2
  12. package/dist/chunks/languages-RMP6DW7H.js.map +7 -0
  13. package/dist/index.ts +28 -8
  14. package/dist/index.ts.map +2 -2
  15. package/package.json +13 -8
  16. package/skills/configuring-pi-starship/SKILL.md +113 -0
  17. package/skills/configuring-pi-starship/references/configuration.md +365 -0
  18. package/skills/configuring-pi-starship/references/module-catalog.md +978 -0
  19. package/skills/configuring-pi-starship/references/modules.md +230 -0
  20. package/skills/configuring-pi-starship/references/runtime-and-security.md +217 -0
  21. package/skills/configuring-pi-starship/scripts/apply.mjs +64 -0
  22. package/skills/configuring-pi-starship/scripts/config-path.mjs +11 -0
  23. package/skills/configuring-pi-starship/scripts/script-support.mjs +20 -0
  24. package/skills/configuring-pi-starship/scripts/validate.mjs +30 -0
  25. package/src/modules/catalog.ts +1 -1
  26. package/src/pi-starship.ts +34 -2
  27. package/src/runtime/cloud.ts +3 -2
  28. package/src/runtime/development.ts +1 -1
  29. package/src/runtime/execution.ts +1 -1
  30. package/src/runtime/languages.ts +1 -1
  31. package/dist/chunks/cloud-GEBXIN43.js.map +0 -7
  32. package/dist/chunks/languages-QR3XPRVQ.js.map +0 -7
  33. /package/dist/chunks/{commands-Z3V7LRUY.js.map → commands-53ZO2JUK.js.map} +0 -0
package/README.md CHANGED
@@ -16,6 +16,7 @@ The extension parses and renders the footer itself, so it does not need the `sta
16
16
  - Wraps native multiline layouts to terminal width instead of truncating them.
17
17
  - Keeps rendering pure while refreshing filesystem, process, and network-derived data through bounded caches.
18
18
  - Uses `/starship` for presets, preview, configuration health, searchable module details, customization, and recovery.
19
+ - Bundles the authoritative configuration skill and references for editing `pi-starship.toml` or answering setup questions.
19
20
  - Loads a generated split runtime to reduce Pi package startup work.
20
21
 
21
22
  ## 📦 Install
@@ -38,7 +39,7 @@ pi -e ./packages/pi-starship
38
39
  ```
39
40
 
40
41
  The package declares `dist/index.ts`, so build an unbuilt local checkout before Pi loads the package directory.
41
- Install only from sources you trust because Pi extensions run with Pi's permissions.
42
+ Install only from sources you trust because Pi extensions and skills run with Pi's permissions.
42
43
  Do not enable this with `@narumitw/pi-statusline`: both own Pi's footer, and Pi does not arbitrate that conflict.
43
44
 
44
45
  ## 🚀 Quick start
@@ -46,702 +47,92 @@ Do not enable this with `@narumitw/pi-statusline`: both own Pi's footer, and Pi
46
47
  Start Pi with the extension to use the built-in footer without creating a settings file.
47
48
  Run `/starship` to inspect the footer, choose a preset, or customize the configuration.
48
49
 
49
- ## 💬 Commands
50
-
51
- | Command | Purpose |
52
- | --- | --- |
53
- | `/starship` | Open the current-state menu in TUI mode; show help in RPC |
54
- | `/starship settings` | Edit, preview, and confirm TOML in TUI; show the file path in RPC |
55
- | `/starship status` | Show the configuration source, path, and diagnostics in TUI or RPC |
56
- | `/starship help` | Show command and configuration help in TUI or RPC |
57
-
58
- The main menu keeps seven actions on one level: **Customize footer**, **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
59
- It shows the current source and configuration health.
60
- Presets, Explain, Modules, and Configuration are menu-only; they do not add textual subcommands.
61
- Restore is unavailable when there is no document to replace.
62
-
63
- The TOML editor, live footer previews, Explain view, module inspector, and configuration reviews use specialized TUI screens.
64
- Their content and key hints adapt to terminal width and Pi's configured keybindings.
65
- Escape returns to the previous screen, while Ctrl+C closes the workflow.
66
- Direct routes reject trailing arguments.
67
- Print and JSON modes produce no ad hoc output, and footer lifecycle work runs only in TUI mode.
68
-
69
- ## ⚙️ Settings
70
-
71
- The only configuration source is:
50
+ The bundled configuration skill is manual-only and is not available for automatic model invocation.
51
+ Run `/skill:configuring-pi-starship` before asking Pi to explain or edit `pi-starship.toml`:
72
52
 
73
53
  ```text
74
- <getAgentDir()>/pi-starship.toml
75
- ```
76
-
77
- When this file is absent, the extension uses its palette-free default without creating the file or its parent directory.
78
- The built-in root is the explicit sequence `$brand$model$thinking$directory` `$git_branch$git_status$activity$context$time`; it does not start the opt-in GitHub PR query.
79
- The first successful settings save creates the file atomically.
80
- Existing malformed documents are never overwritten.
81
-
82
- The extension does **not** read project overrides, `pi-statusline.json`, `PI_STATUSLINE_PRESET`, or `~/.config/starship.toml`, and does not migrate statusline settings.
83
-
84
- Open the interactive menu in TUI mode:
85
-
86
- ```text
87
- /starship
88
- ```
89
-
90
- Choose **Customize footer** to edit the TOML.
91
- Closing the editor validates the draft and opens a scrollable preview with **Apply changes…**, **Continue editing**, and **Discard draft**.
92
- Saving requires separate confirmation, then atomically updates the file and active footer.
93
- Manual TOML edits load at the next `session_start`, including `/reload` and session replacement.
94
- Cancellation, disposal, invalid drafts, write failures, and runtime application failures preserve the previous file and footer.
95
-
96
- The shallow main menu also exposes **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
97
- Explain footer uses the current immutable runtime snapshot to list each currently showing non-empty module once with its rendered value and description; it starts no new collection work.
98
- Modules opens a bounded searchable inspector for every registered module.
99
- Its textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and **Unavailable** only when the current footer cannot provide an inspection snapshot.
100
- Module detail shows the current preview when available, description, root reference and reachability, format variables, style fields, display rules, and the known reason for absent output.
101
- Both views are read-only and do not create or update the settings document.
102
-
103
- Configuration contains **Overview**, **Effective configuration**, **Settings document**, and **Reload from disk** on one nested level.
104
- Overview combines state, source, path, health, and bounded diagnostics.
105
- Effective configuration shows deterministic catalog-ordered public TOML from the normalized state currently in use; comments, unknown fields, parser ASTs, and private runtime selectors are excluded.
106
- Settings document shows the exact loaded UTF-8 text through a terminal-safe, cell-aware read-only review without changing the raw payload.
107
- A missing file is **Built-in defaults**, an exact bundled document uses its preset name, and read or parse errors are **Built-in fallback**.
108
- Reload from disk reads only after the explicit action, validates and previews the current external state from the existing runtime snapshot, and asks for separate confirmation before changing the active session.
109
- A deleted document is a valid previewable transition to built-in defaults and creates no file.
110
- An unchanged document is a no-op, while read or parse failure, cancellation, disposal, external changes after preview, session replacement, shutdown, or runtime apply failure preserves the prior effective footer and every file byte.
111
- Reload re-reads immediately after confirmation and rejects a different external snapshot; it does not claim cross-process locking or continuing synchronization with later edits.
112
- Restore is disabled when no settings document exists or the exact built-in document is already saved.
113
- For a custom or invalid document, Restore previews the result and warns that the complete document, including custom settings, unknown fields, and comments, will be replaced without a post-success backup before asking for confirmation.
114
-
115
- ### 🎛️ Presets
116
-
117
- Choose **Presets** from `/starship` to browse complete Pi-native starting points.
118
- The catalog adapts all styles listed by `starship preset --list` in Starship 1.26.0, plus a Pi-specific Minimal option.
119
- Colors, separators, typography, and layout follow the named Starship preset; modules are deliberately selected for Pi's model, thinking, workspace, Git, activity, context, and time snapshots.
120
-
121
- | Preset | Adapted visual treatment | Font requirement |
122
- | --- | --- | --- |
123
- | **Minimal** | Compact Pi essentials | Standard Unicode |
124
- | **Bracketed Segments** | Balanced Pi and Git information in brackets | Standard Unicode |
125
- | **Catppuccin Powerline** | Connected Catppuccin Mocha blocks; other Catppuccin palettes remain in the document for customization | Nerd Font |
126
- | **Gruvbox Rainbow** | Warm Gruvbox connected segments | Nerd Font |
127
- | **Jetpack** | Airy geometric activity/context and workspace columns joined by fill | Standard Unicode |
128
- | **Nerd Font Symbols** | Balanced default layout with icon-rich symbols | Nerd Font |
129
- | **No Empty Icons** | Conditional text labels that cannot appear without their values | Standard Unicode |
130
- | **No Nerd Font** | Portable Unicode symbols without private-use glyphs | Standard Unicode |
131
- | **No Runtime Versions** | Presence indicators without model or thinking details | Standard Unicode |
132
- | **Pastel Powerline** | Connected magenta, coral, orange, blue, teal, and navy blocks | Nerd Font |
133
- | **Plain Text Symbols** | Plain words replace pictograms | Standard Unicode |
134
- | **Pure Preset** | Clean two-line workspace and session context | Standard Unicode |
135
- | **Tokyo Night** | Connected cool blue Tokyo Night blocks | Nerd Font |
136
-
137
- Moving through the preset picker temporarily renders the selected preset in the footer without writing settings or starting collectors.
138
- Press Enter to confirm replacement, or press `e` to edit the selected complete TOML document before preview and confirmation.
139
- Escape returns to the main menu, while Ctrl+C closes the workflow; both restore the active footer.
140
-
141
- Presets are complete documents, not overlays.
142
- After confirmation, applying one replaces all of `pi-starship.toml`, including custom settings, unknown fields, and comments; no backup is kept.
143
- Cancellation, disposal, validation failure, write failure, and runtime-apply failure preserve the previous document and footer.
144
- An exact match is **Currently applied** and cannot be selected again; editing any byte makes it custom.
145
- Use **Restore built-in…** for deterministic recovery.
146
-
147
- The bundled presets use only pi-starship's local Pi and Git snapshot modules.
148
- They do not enable the GitHub PR query, cloud/deployment readers, or optional command-backed workspace collectors.
149
- They are Pi-native adaptations of the color and format treatments emitted by Starship 1.26.0; they do not copy Starship's module selections because Pi exposes different runtime information.
150
- There is no `/starship preset` textual route and no remote preset download.
151
-
152
- ### 📝 Example
153
-
154
- ```toml
155
- format = """
156
- $brand\
157
- $model\
158
- $thinking\
159
- $directory\
160
- $git_branch\
161
- $git_status\
162
- $activity\
163
- $context\
164
- $time"""
165
-
166
- [model]
167
- format = "[ $symbol$model ]($style)"
168
- symbol = "◆ "
169
- style = "bold blue"
170
- truncation_length = 36
171
- truncation_symbol = "…"
172
- truncation_direction = "middle"
173
-
174
- [directory]
175
- style = "cyan bold"
176
-
177
- [git_branch]
178
- style = "bold purple"
179
-
180
- [context]
181
- format = "[$symbol $percentage/$window ]($style)"
182
-
183
- [[context.display]]
184
- threshold = 0
185
- style = "bold green"
186
- hidden = true
187
-
188
- [[context.display]]
189
- threshold = 30
190
- style = "bold green"
191
- hidden = false
192
-
193
- [[context.display]]
194
- threshold = 60
195
- style = "bold yellow"
196
- hidden = false
197
-
198
- [[context.display]]
199
- threshold = 80
200
- style = "bold red"
201
- hidden = false
202
-
203
- [git_metrics]
204
- added_style = "bold green"
205
- deleted_style = "bold red"
206
- disabled = false
207
-
208
- [username]
209
- style_user = "yellow bold"
210
- style_root = "red bold"
211
-
212
- [extension_status]
213
- format = "([$statuses ]($style))"
214
- icons = { "foo:*" = "🧪", "third_party/key" = "◎", fallback = "•" }
215
- ```
216
-
217
- Every module table supports `format`, `symbol`, and `disabled`.
218
- Most modules also support one `style`.
219
- The exceptions are `git_metrics` (`added_style` and `deleted_style`), `username` (`style_user` and `style_root`), and the threshold-selected `context` and `cost` `display` arrays described below.
220
- `thinking` retains its `style` fallback and also accepts the per-level overrides documented below.
221
- Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
222
- Version formats replace `$raw`.
223
- Detection arrays replace defaults when non-empty and inspect only one listing of the current directory.
224
- A leading `!` is supported by language detection arrays and rejects a matching project.
225
- `[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace wildcards such as `foo:*`; `fallback` controls unmatched statuses.
226
- Icon matching uses the exact key, the longest `:*` wildcard, a leading status emoji, then `fallback`/`🔌`.
227
- An empty configured icon suppresses only the icon.
228
- `foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
229
-
230
- Pi does not expose status ownership, so exact raw keys are the reliable third-party contract.
231
- pi-starship does not inspect installed packages, infer aliases, assign known-extension icons, or bridge compatibility keys.
232
- Extension authors may use `<extension-id>` or `<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require it.
233
-
234
- **Icon migration:** configurations that relied on package-ID aliases, built-in known-extension icons, or compatibility mappings must use an exact raw status key, an explicit namespace wildcard, a leading emoji in the status value, or `fallback`.
235
-
236
- ## 🧩 Format grammar
237
-
238
- - Variables: `$name` and `${name}`.
239
- Unknown variables render empty and produce a warning when loaded from TOML.
240
- - Escapes: `\\$`, `\\[`, `\\]`, `\\(`, `\\)`, and `\\\\` render functional characters literally.
241
- - Styled groups: `[format string](style string)`.
242
- - Conditional groups: `(format string)` render only when a nested variable has a non-empty value.
243
- - Nested groups are supported.
244
- - `$all` expands enabled modules in the default order and omits modules already referenced explicitly.
245
-
246
- Module formats can use `$style` in a style expression.
247
- Module output keeps its own style when embedded in an outer styled group.
248
-
249
- ## 🎨 Styles and palettes
250
-
251
- Style expressions support:
252
-
253
- - Named colors and ANSI numbers `0`–`255`.
254
- - Hex RGB (`#7aa2f7`), rendered as ANSI-256 when Pi's effective terminal capabilities disable true color.
255
- - `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
256
- - `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
257
- - `none` and `fg:none`, which make the complete expression unstyled regardless of position.
258
- - `bg:none`, which clears only the absolute background; an unknown `bg:<value>` has the same Starship-compatible reset behavior.
259
- - `prev_fg` and `prev_bg`, which use the previous rendered chunk's colors when present and retain any absolute foreground/background in the expression as the no-previous fallback.
260
- - Direct color names from one explicitly selected `[palettes.<name>]` table.
261
-
262
- There is no built-in or fallback palette.
263
- A custom palette is active only when its table is explicitly selected, and its values must be direct named, ANSI, or RGB colors—palette entries cannot reference other entries.
264
- Palette names override terminal color names such as `blue`:
265
-
266
- ```toml
267
- palette = "company"
268
-
269
- [palettes.company]
270
- blue = "#86BBD8"
271
- accent = "208"
272
-
273
- [model]
274
- style = "bold blue"
54
+ /skill:configuring-pi-starship explain the aws module
55
+ /skill:configuring-pi-starship enable the directory and git_branch modules
275
56
  ```
276
57
 
277
- Style tokens are case-insensitive and ordinary foreground/background colors are last-wins.
278
- `prev_fg`/`prev_bg` override their absolute fallback only when a previous chunk exists.
279
- Empty styled groups still advance previous-color state.
280
- Invalid literal style expressions warn and render unstyled.
281
- An invalid root format falls back to the built-in root format; an invalid module format or catalog-owned style field falls back only at that field's module scope.
282
- `/starship status` reports warnings.
283
-
284
- The background-free defaults are: `brand = "bold white"`, `provider`/`model` = `"bold blue"`, `thinking`/`git_branch`/`turn` = `"bold purple"`, `directory`/`git_worktree` = `"cyan bold"`, `github_pr = "bold blue"`, `git_commit = "green bold"`, `git_state`/`activity`/`time` = `"bold yellow"`, `git_status = "red bold"`, `tokens = "bold cyan"`, `cache = "bold green"`, `extension_status = "dimmed white"`, `direnv = "bold bright-yellow"`, and `fill = "bold black"`.
285
- Context, cost, Git metrics, and username use the state/multi-style defaults below.
58
+ The skill loads the relevant reference and validates file edits.
59
+ It does not cover general TOML, shell Starship configuration, extension source development, or unrelated footer work.
286
60
 
287
- ### Thinking level styles
288
-
289
- `thinking` can override its appearance for `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` independently:
61
+ ## 💬 Commands
290
62
 
291
- ```toml
292
- [thinking]
293
- style = "bold purple"
294
- style_low = "bold blue"
295
- style_high = "bold yellow"
296
- style_max = "bold red"
297
- ```
63
+ | Command | Purpose |
64
+ | --- | --- |
65
+ | `/starship` | Customize the footer, preview presets, inspect modules, or restore built-in configuration; RPC shows help. |
66
+ | `/starship settings` | Edit, preview, and confirm TOML; RPC shows the file path. |
67
+ | `/starship status` | Show the configuration source, path, and diagnostics. |
68
+ | `/starship help` | Show command and configuration help. |
298
69
 
299
- The matching `style_<level>` wins when it is non-empty.
300
- Every unset or empty level override uses the existing `style`, including levels added by a future Pi release.
301
- Invalid fallback and level styles warn and fall back independently without changing other levels.
70
+ All routes support TUI and RPC with the exceptions above and reject unknown or trailing arguments.
71
+ Print and JSON modes produce no command output; the footer runs only in TUI mode.
72
+ Preset selection, module inspection, and recovery are menu-only, not extra subcommands.
73
+ Restoring built-in configuration requires an existing settings document to replace; see [Settings](#-settings).
302
74
 
303
- ### State-selected styles
75
+ ## ⚙️ Settings
304
76
 
305
- `context` and `cost` select the last entry at the highest threshold less than or equal to the current value.
306
- A later entry wins when thresholds are equal.
307
- Each display entry requires a finite `threshold`, a valid `style`, and boolean `hidden`.
308
- Invalid entries warn and are ignored; module defaults are used if none remain.
77
+ The package bundles the `configuring-pi-starship` skill as the authoritative configuration guide for users and agents.
78
+ Invoke `/skill:configuring-pi-starship` before asking Pi how to configure the footer or edit `pi-starship.toml`.
79
+ The skill answers from its references and consults the bundled source only when the public documentation does not cover a question.
309
80
 
310
- The default context thresholds are hidden at `0`, `bold green` at `30`, `bold yellow` at `60`, and `bold red` at `80`.
311
- The default cost thresholds are hidden at `0`, `bold yellow` at `1`, and `bold red` at `5`:
81
+ Read the references directly when preferred:
312
82
 
313
- ```toml
314
- [[cost.display]]
315
- threshold = 0
316
- style = "bold green"
317
- hidden = true
318
-
319
- [[cost.display]]
320
- threshold = 1
321
- style = "bold yellow"
322
- hidden = false
323
-
324
- [[cost.display]]
325
- threshold = 5
326
- style = "bold red"
327
- hidden = false
328
- ```
83
+ - [Configuration and format](./skills/configuring-pi-starship/references/configuration.md) — settings schema, validation and fallback behavior, presets, examples, format grammar, styles, palettes, and display thresholds.
84
+ - [Complete module catalog](./skills/configuring-pi-starship/references/module-catalog.md) — exact variables, default formats, symbols, enabled state, style fields, display defaults, option types, ranges, and enum values.
85
+ - [Module behavior](./skills/configuring-pi-starship/references/modules.md) — reachability, exact detection defaults, command gates, output semantics, aliases, truncation, and module-specific behavior.
86
+ - [Runtime and security](./skills/configuring-pi-starship/references/runtime-and-security.md) — network and command execution, local metadata, cloud and deployment context, fill layout, refresh behavior, and limitations.
329
87
 
330
- `git_metrics` exposes `$added_style` and `$deleted_style` in its module format.
331
- `username` still uses `$style` in its format, but selects `style_user` or `style_root` from private execution metadata; the selector is not a format variable.
332
-
333
- ### Breaking palette migration
334
-
335
- The previous implicit `tokyo-night` palette and its `lead`, `header`, `header_fg`, `directory`, `directory_fg`, `git`, `git_fg`, `runtime`, `runtime_fg`, `meter`, `meter_fg`, and `extension` aliases were removed.
336
- Existing files are not rewritten.
337
- Old alias-based module styles warn and fall back to the module's new direct-color default; alias-based literal Powerline groups warn and render unstyled.
338
-
339
- Choose one migration:
340
-
341
- 1. Replace old aliases with direct styles such as `cyan bold`, `bold bright-yellow`, or `fg:#e3e5e5 bg:#769ff0`.
342
- 2. Define every needed alias under your own `[palettes.<name>]` table and explicitly select it with `palette = "<name>"`.
343
- 3. Use **Restore built-in…** from `/starship` to review and replace the complete document with the new plain nine-module configuration.
344
-
345
- There is no hidden compatibility overlay or automatic migration.
346
-
347
- ## 🧱 Modules
348
-
349
- | Module | Format variables | Meaning |
350
- | --- | --- | --- |
351
- | `brand` | `$symbol` | Pi brand marker |
352
- | `provider` | `$symbol`, `$provider` | Current model provider |
353
- | `model` | `$symbol`, `$model` | Current model name |
354
- | `thinking` | `$symbol`, `$level` | Thinking level |
355
- | `directory` | `$symbol`, `$path`, `$full_path` | Current working directory |
356
- | `git_worktree` | `$symbol`, `$name`, `$path` | Linked worktree name and top-level path |
357
- | `git_branch` | `$symbol`, `$branch`, `$remote_name`, `$remote_branch` | Local branch and upstream |
358
- | `github_pr` | `$symbol`, `$number`, `$link`, `$state`, `$checks`, `$review`, `$status` | Current-branch GitHub pull request |
359
- | `git_commit` | `$symbol`, `$hash`, `$tag` | Seven-character HEAD hash and optional exact tag |
360
- | `git_state` | `$symbol`, `$state`, `$progress_current`, `$progress_total` | Rebase, merge, revert, cherry-pick, bisect, or mail-apply state |
361
- | `git_metrics` | `$symbol`, `$added`, `$deleted` | Added/deleted line totals from the working tree diff |
362
- | `git_status` | `$symbol`, `$all_status`, `$ahead_behind`, `$ahead`, `$behind`, `$diverged`, `$up_to_date`, `$conflicted`, `$stashed`, `$deleted`, `$renamed`, `$modified`, `$typechanged`, `$staged`, `$untracked`, and detailed index/worktree counters | Cached porcelain-v2 counters |
363
- | `activity` | `$symbol`, `$state`, `$tool`, `$count`, `$kind`, `$title`, `$text` | Extension UI waits, active tools, streaming, completion, or idle |
364
- | `context` | `$symbol`, `$percentage`, `$tokens`, `$window` | Context-window use |
365
- | `tokens` | `$symbol`, `$input`, `$output`, `$total` | Token totals |
366
- | `cache` | `$symbol`, `$rate`, `$read`, `$write` | Prompt-cache reads, writes, and latest hit rate; disabled by default |
367
- | `cost` | `$symbol`, `$cost`, `$subscription` | Session cost and optional `(sub)` marker |
368
- | `time` | `$symbol`, `$time` | Current local time |
369
- | `turn` | `$symbol`, `$count` | User turn count |
370
- | `package` | `$symbol`, `$version`, `$source` | Direct project manifest version |
371
- | `nodejs` | `$symbol`, `$version`, `$engines_version` | Detected Node.js project/runtime |
372
- | `python` | `$symbol`, `$version`, `$virtualenv`, `$pyenv_prefix` | Python runtime and allowlisted environment name |
373
- | `rust` | `$symbol`, `$version`, `$numver`, `$toolchain` | Safe native `rustc` runtime and allowlisted toolchain name |
374
- | `golang` | `$symbol`, `$version`, `$mod_version` | Go runtime (`$mod_version` is reserved and currently empty) |
375
- | `bun` / `deno` | `$symbol`, `$version` | Bun or Deno runtime |
376
- | `mise` | `$symbol`, `$health` | Bounded mise health result |
377
- | `direnv` | `$symbol`, `$rc_path`, `$allowed`, `$loaded` | Inert direnv status; `.envrc` is never sourced |
378
- | `conda` | `$symbol`, `$environment` | Active Conda environment name |
379
- | `pixi` | `$symbol`, `$version`, `$environment`, `$project_name` | Pixi project and environment |
380
- | `nix_shell` | `$symbol`, `$state`, `$name`, `$level` | Allowlisted Nix shell activation metadata |
381
- | `guix_shell` | `$symbol`, `$state` | Guix shell activation marker |
382
- | `docker_context` | `$symbol`, `$context` | Non-default local Docker context |
383
- | `kubernetes` | `$symbol`, `$context`, `$namespace`, `$cluster`, `$user` | Current inert kubeconfig metadata |
384
- | `terraform` | `$symbol`, `$workspace`, `$version` | Local Terraform/OpenTofu workspace and optional version |
385
- | `aws` | `$symbol`, `$profile`, `$region` | AWS profile/region metadata, never credentials |
386
- | `gcloud` | `$symbol`, `$active`, `$account`, `$domain`, `$project`, `$region` | Active gcloud configuration metadata |
387
- | `azure` | `$symbol`, `$subscription`, `$username` | Default Azure subscription; username is separately enabled |
388
- | `openstack` | `$symbol`, `$cloud`, `$project` | Selected OpenStack cloud/project metadata |
389
- | `os` | `$symbol`, `$type`, `$name`, `$version`, `$edition`, `$codename` | Platform/OS metadata; disabled by default |
390
- | `container` | `$symbol`, `$name`, `$type` | Known container, WSL, or Dev Container context |
391
- | `hostname` | `$symbol`, `$hostname`, `$ssh_symbol` | Hostname, SSH-only by default |
392
- | `username` | `$symbol`, `$user` | Contextual login identity |
393
- | `fill` | `$symbol` | Flexible width-aware root-layout marker |
394
- | `extension_status` | `$symbol`, `$statuses`, `$count` | Pi extension statuses |
395
-
396
- ### Usage semantics
397
-
398
- - During a blocking extension UI prompt, `activity` sets `$state` to `waiting`, `$kind` to the prompt kind, and `$title` to the sanitized bounded title or an empty string.
399
- - Prompt waiting takes precedence without losing the underlying tool, streaming, completed, or idle state, which returns when the prompt closes.
400
- - `tokens`, `cache`, and `cost` total every usage-bearing session entry, matching Pi's native footer.
401
- This includes assistant messages, nested-LLM tool results, compactions, and branch summaries, including abandoned branches retained in the session.
402
- - Cache `$read` and `$write` are cumulative.
403
- `$rate` uses only the latest assistant prompt with `cacheRead / (input + cacheRead + cacheWrite) * 100`.
404
- The module is empty when Pi has reported no cache reads or writes.
405
- - `cache` is disabled and absent from the built-in root.
406
- Enable it and add `$cache` to a custom root format (or use `$all`) to display it.
407
- - Context `$percentage` uses native one-decimal precision.
408
- Its default display hides values below 30%.
409
- Customize `[[context.display]]` when lower values should remain visible.
410
- The module name remains `context`, not `context_usage`.
411
- - Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`.
412
- The dollar value is usage cost, not proof of an amount billed under a subscription.
413
-
414
- ### Directory, Git, and environment contraction
415
-
416
- The analogous modules keep their display policy local and use Starship defaults:
88
+ The only configuration source remains `<getAgentDir()>/pi-starship.toml`.
89
+ A minimal custom document can select and style only the modules it needs:
417
90
 
418
91
  ```toml
419
- [directory]
420
- truncation_length = 3
421
- truncate_to_repo = true
422
- fish_style_pwd_dir_length = 0
423
- truncation_symbol = ""
424
- home_symbol = "~"
425
- use_os_path_sep = true
426
- substitutions = { "/Volumes/network/path" = "/net" }
427
-
428
- [git_branch]
429
- truncation_length = 0 # pi-starship's bounded no-truncation sentinel
430
- truncation_symbol = "…"
431
-
432
- [git_commit]
433
- commit_hash_length = 7
434
-
435
- [conda]
436
- ignore_base = true
437
- truncation_length = 1
438
-
439
- [hostname]
440
- trim_at = "." # set to "" to keep the complete hostname
441
- ```
442
-
443
- Directory `$path` contracts the home directory and, by default, the current Git repository root before retaining the last three path components.
444
- `$full_path` remains the unmodified absolute cwd.
445
- A positive `fish_style_pwd_dir_length` abbreviates otherwise omitted parent components when no substitution is configured.
446
- `substitutions` is an ordered TOML string table of literal replacements.
447
- Pi exposes one cwd rather than separate logical and physical paths, and pi-starship does not implement Starship's regex substitution array or repo-root-specific split style/format fields.
448
- Directory rendering reads only immutable home and repository-root snapshot data and performs no filesystem or Git work.
449
-
450
- Git branch truncation retains the first `N` grapheme clusters and appends the first grapheme of `truncation_symbol` only when truncation occurs.
451
- The same rule applies independently to `$branch`, `$remote_name`, and `$remote_branch`.
452
- Upstream Starship represents its unlimited default as `2^63 - 1`; pi-starship uses `0` for the same behavior because its settings integers are deliberately bounded.
453
- `commit_hash_length` accepts 0 through 64.
92
+ format = "$model$directory$git_branch"
454
93
 
455
- Conda retains the last path component by default; `0` keeps the complete environment path.
456
- Hostname trimming runs before exact alias lookup, matching Starship.
457
- These transformations affect display only.
458
- Collectors retain bounded, control-sanitized source metadata.
459
-
460
- ### Model and provider aliases and model truncation
461
-
462
- The model module accepts exact `model_aliases`, Starship-style `truncation_length` and `truncation_symbol` options, plus the Pi-specific `truncation_direction` option:
463
-
464
- ```toml
465
94
  [model]
466
- model_aliases = { "/models/Qwen3.6-35B-Q4.gguf" = "Qwen 35B Q4" }
467
- truncation_length = 36
468
- truncation_symbol = "…"
469
- truncation_direction = "middle"
470
- ```
471
-
472
- An exact alias is selected before the built-in Claude/GPT shortening rules, then the resulting label is subject to the configured truncation.
473
- `truncation_length` counts model grapheme clusters retained before the symbol; `0` disables truncation and is the default.
474
- The direction names the removed portion: `start` retains the suffix, `end` retains the prefix and is the default, and `middle` retains both ends.
475
- When no alias matches, truncation runs after the built-in Claude/GPT shortening rules.
476
- Truncation changes display only; the provider model ID is untouched.
477
- Terminal control sequences in model IDs and truncation symbols are removed at render time.
478
- An empty symbol truncates without a marker.
479
-
480
- The provider module accepts exact display aliases without changing the selected provider or model:
481
-
482
- ```toml
483
- [provider]
484
- provider_aliases = { "openai-codex" = "codex", "amazon-bedrock" = "bedrock" }
95
+ style = "bold blue"
485
96
  ```
486
97
 
487
- An empty alias hides only the provider text.
488
- Provider names and aliases are stripped of terminal controls at render time.
489
- For example, `middle` can retain both a Hugging Face model family and its variant, while `start` is useful when a llama.cpp server reports an absolute model path.
490
- pi-starship treats model IDs as opaque strings and does not parse paths, repositories, GGUF suffixes, or quantization names.
491
-
492
- `truncation_direction` is a pi-starship adaptation; upstream Starship has no model module or generic truncation-direction setting.
493
-
494
- `git_worktree` is empty in the primary worktree.
495
- In a linked worktree it defaults to the top-level directory name; use `$path` when the full absolute path is needed.
496
-
497
- `git_commit`, `git_state`, and `git_metrics` are intentionally not present in the built-in root format.
498
- Add their variables to `format` to opt in; also set `[git_metrics].disabled = false`, matching Starship's opt-in metrics default.
499
- `$tag` resolves only an exact tag on HEAD and is queried only when the configured `git_commit` format references it.
98
+ Use `/starship` for interactive configuration, preview, diagnostics, presets, and recovery.
99
+ Manual file edits load at the next `session_start`, including `/reload`.
500
100
 
501
101
  ## 🔒 Security and privacy
502
102
 
503
- ### 🔎 Native GitHub pull requests
504
-
505
- `$github_pr` is independent of `pi-github-pr`; installing that extension is not required.
506
- It runs one bounded GitHub CLI query for the current branch:
507
-
508
- ```text
509
- gh pr view --json number,isDraft,url,state,closedAt,mergedAt,reviewDecision,statusCheckRollup
510
- ```
511
-
512
- Install and authenticate `gh` first:
513
-
514
- ```bash
515
- gh auth login
516
- ```
517
-
518
- For GitHub Enterprise Server, authenticate the repository host and keep that host in the repository remote, for example `gh auth login --hostname github.example.com`. pi-starship starts `gh` directly with child-only environment data that omits ambient `GH_HOST` and `GH_REPO` overrides, so `gh` resolves the correct repository and host from the current checkout.
519
- It never mutates Pi's environment, calls the GitHub API directly, or manages tokens.
520
-
521
- Variables have these values:
522
-
523
- - `$number`: digits such as `123`.
524
- - `$link`: an OSC 8 `#123` link for a safe HTTP(S) URL when Pi's effective terminal capabilities enable hyperlinks, otherwise plain `#123`.
525
- - `$state`: `open`, `draft`, `merged`, or `closed`.
526
- - `$checks`: all non-zero check counts in passed, failed, pending order, or `-` when no checks exist.
527
- - `$review`: `R✓` for approved, `R×` for changes requested, `R?` for review required, or empty when unknown.
528
- - `$status`: one result selected in this order: merged, closed, draft, failing checks, changes requested, pending checks, approved, review required, passing checks, then no checks.
529
-
530
- The compact symbols are font-safe and distinct from Git's default `$`, `!`, and `?` worktree markers:
531
-
532
- | Compact value | Meaning |
533
- | --- | --- |
534
- | `✓<n>` | Checks that passed, including successful, skipped, and neutral conclusions |
535
- | `×<n>` | Checks that failed |
536
- | `…<n>` | Checks that are pending |
537
- | `R✓` | Review approved |
538
- | `R×` | Changes requested |
539
- | `R?` | Review required |
540
- | `M` / `C` / `D` | Merged, closed, or draft PR |
541
- | `-` | No checks |
542
-
543
- The unchanged default module format uses `$status` and now renders compact output:
544
-
545
- ```text
546
- PR #123 · ×2
547
- PR #123 · R✓
548
- PR #123 · M
549
- ```
550
-
551
- Use the existing `$checks` and `$review` variables together when every check category and the review result should remain visible:
552
-
553
- ```toml
554
- [github_pr]
555
- format = "[$symbol$link( $checks)( $review) ]($style)"
556
- ```
557
-
558
- ```text
559
- PR #123 ✓12 ×2 …7 R×
560
- ```
561
-
562
- This is a breaking display migration for custom formats that use these variables:
563
-
564
- | Previous value | Compact value |
565
- | --- | --- |
566
- | `checks passing` | `✓<n>` |
567
- | `<n> failing` | `×<n>` |
568
- | `<n> pending` | `…<n>` |
569
- | `no checks` | `-` |
570
- | `approved` / `changes requested` / `review required` | `R✓` / `R×` / `R?` |
571
- | `merged` / `closed` / `draft` | `M` / `C` / `D` |
572
-
573
- The old English values have no verbose aliases.
574
- The variable names and default module format remain unchanged, so no TOML field migration is needed.
575
-
576
- The query runs only in TUI sessions when the enabled module is reachable from the root format.
577
- It refreshes at session start, immediately after a branch change, after each agent run, after accepted settings changes, and every 60 seconds.
578
- Each query has a 10-second timeout.
579
- Branch changes clear the old PR before querying the new branch.
580
- Closed and merged PRs remain visible for 24 hours, then expire without waiting for the next refresh.
581
- Missing `gh`, missing authentication, no current PR, timeout, malformed or oversized output, and network failures all render an empty module without exposing raw errors or credentials.
582
-
583
- The query sends the repository and current branch through authenticated `gh` to the repository's configured GitHub host.
584
- It requests only the fields above—never comments, review bodies, inline comments, or review threads.
585
- Footer rendering and previews read only the immutable cached snapshot and perform no network or subprocess work.
586
-
587
- **Breaking migration:** `$git_branch.$pr` has been removed without a compatibility alias or automatic migration.
588
- Replace it with root `$github_pr` and an optional `[github_pr]` table.
589
- If `pi-github-pr` remains installed, its independent `github-pr` status can also appear under `$extension_status`.
590
- Disable or remove that extension when adopting the native module to avoid duplicate information.
591
-
592
- ### 📦 Package and language modules
593
-
594
- Module behavior is inspired by Starship pinned at `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; formatter style semantics and the approved multi/state-style surfaces are aligned with the checked-in Starship source at `cad50cd8`.
595
- This is not complete Starship module or configuration compatibility.
596
-
597
- | Area | Adopted | Adapted | Intentionally omitted |
598
- | --- | --- | --- | --- |
599
- | `package` | `package.json` → Cargo → PEP 621/Poetry precedence, `$version` | Direct manifests only; Cargo workspace version lookup is capped at eight ancestors | Other package ecosystems, dynamic Python versions, package-manager execution |
600
- | Node.js | Direct markers/extensions, `node --version`, package engine text | Bun/Deno markers suppress Node's default detection | Constraint checks and manager/shim evaluation |
601
- | Python | Direct markers, selected interpreter `--version`, virtualenv name | Interpreter selection uses only an existing active virtualenv path or `python` | Python code execution and broad environment discovery |
602
- | Rust | Direct markers and native `rustc --version` | `.cargo`/`.rustup` shim paths are rejected to avoid toolchain installation | Falling back to rustup or any installing probe |
603
- | Go | Direct markers and `go version` | `$mod_version` stays empty | `go list`, module downloads, and constraint enforcement |
604
- | Bun / Deno | Direct markers and `bun --version` / `deno -V` | Negative detection avoids overlapping Node defaults | Runtime installation and recursive source detection |
605
-
606
- All runtime commands use argv execution in `ctx.cwd`, a 2-second timeout, and 64 KiB accepted output.
607
- Commands run only when the reachable module format references the command-backed variable.
608
- Missing, killed, oversized, or malformed commands clear that value independently.
609
- `version_format`, `detect_files`, `detect_extensions`, and `detect_folders` are available on language modules; package supports `version_format`.
610
-
611
- ### 🧰 Development environments
612
-
613
- | Module | Detection / allowed inputs | Optional command | Options |
614
- | --- | --- | --- | --- |
615
- | `mise` | Direct `mise.toml`, `.mise.toml`, or `.tool-versions` | `mise doctor` only for `$health` | Detection arrays |
616
- | `direnv` | Direct `.envrc`; the file is never read or sourced | `direnv status --json` only for status variables | Detection arrays |
617
- | `conda` | `CONDA_DEFAULT_ENV` only | None | `ignore_base` (default `true`) |
618
- | `pixi` | Direct `pixi.toml`/`pixi.lock`, `PIXI_ENVIRONMENT_NAME`, `PIXI_PROJECT_NAME` | `pixi --version` only for `$version` | Detection arrays, `version_format`, `show_default_environment` |
619
- | `nix_shell` | `IN_NIX_SHELL`, `NIX_SHELL_NAME`, `NIX_SHELL_LEVEL` | None | None |
620
- | `guix_shell` | Presence of `GUIX_ENVIRONMENT` | None | None |
621
-
622
- The extension never enumerates the process environment, activates a shell, evaluates Nix, lists installed tools, or publishes arbitrary environment values.
623
- Names and paths are control-sanitized and bounded before publication.
624
-
625
- ### 🚢 Deployment and cloud context
626
-
627
- These modules read inert local metadata only.
628
- They do **not** contact Docker, Kubernetes, Terraform/OpenTofu backends, cloud APIs, OAuth flows, credential helpers, or metadata services.
629
- They remain opt-in because context labels may be sensitive.
630
-
631
- - `docker_context`: `DOCKER_CONTEXT`, then `DOCKER_CONFIG/config.json` or `~/.docker/config.json`.
632
- The `default` context is suppressed.
633
- `only_with_files` and detection arrays are supported.
634
- - `kubernetes`: at most `max_config_files` (default 8) from `KUBECONFIG` or `~/.kube/config`, with first-wins merge semantics.
635
- Only context, namespace, cluster name, and user name are selected.
636
- Exact `context_aliases`, `namespace_aliases`, `cluster_aliases`, and `user_aliases` apply.
637
- - `terraform`: direct `.tf`, `.tfplan`, `.tfstate`, or `.terraform`; workspace precedence is `TF_WORKSPACE` → `TF_DATA_DIR/environment` → `.terraform/environment`.
638
- `terraform version`, then `tofu version`, runs only for `$version`.
639
- Workspace, init, provider, and state commands never run.
640
- - `aws`: `AWS_PROFILE`/`AWS_DEFAULT_PROFILE`, `AWS_REGION`/`AWS_DEFAULT_REGION`, then the selected AWS config section.
641
- The credentials file is never read.
642
- Exact profile/region aliases are supported.
643
- - `gcloud`: active selector plus allowlisted `core.account`, `core.project`, and `compute.region` INI keys.
644
- Exact project/region aliases are supported.
645
- - `azure`: the default local `azureProfile.json` subscription name.
646
- `show_username` defaults to `false`; exact subscription aliases are supported.
647
- - `openstack`: `OS_CLOUD`, `OS_PROJECT_NAME`, or the selected `clouds.yaml` `auth.project_name` only.
648
- Exact cloud/project aliases are supported.
649
-
650
- Cloud files often colocate credentials with labels.
651
- Parsers allowlist fields while reading and discard source documents; token, key, password, auth URL, tenant, and credential-derived duration fields never enter snapshots, diagnostics, notifications, or rendered output.
652
- Presence indicates only selected local metadata—not valid credentials or connectivity.
653
-
654
- ### 🖥️ Execution context
655
-
656
- `hostname` is SSH-only by default and supports `ssh_only`, `trim_at`, and exact `aliases`.
657
- `username` appears only for `show_always`, SSH, root/Administrator, a login-user mismatch, or configured `detect_env_vars`; it supports exact aliases.
658
- Negated username detection names are rejected.
659
- `os` is disabled by default and supports an exact `symbols` map.
660
- `container` uses only Dev Container/Codespaces markers, WSL metadata, `/.dockerenv`, `/run/.containerenv`, and `/run/systemd/container`; it does not scan process tables or cgroups.
661
- Ordinary local hostname/username sessions stay empty.
662
- All identity labels are bounded and stripped of C0/C1 controls, ANSI, newlines, and OSC control bytes.
663
-
664
- ## 📐 Layout and lifecycle
665
-
666
- ### ↔️ Fill layout
667
-
668
- Add `${fill}` between left and right root content (braces disambiguate adjacent text):
669
-
670
- ```toml
671
- format = "$directory$git_branch${fill}$model$context"
672
-
673
- [fill]
674
- symbol = " " # native invisible default; use "·" for a visible pattern
675
- style = "dimmed"
676
- ```
677
-
678
- Fill resolves independently on each logical line before ANSI serialization and wrapping.
679
- Multiple fills divide remaining cells left-to-right; complete positive-width patterns repeat and any remainder uses styled spaces.
680
- Empty/zero-width patterns become spaces.
681
- Fixed content is never truncated: when it already meets or exceeds the width, fill contributes zero and normal ANSI-aware wrapping applies.
682
- Unicode wide/combining symbols, palettes, `prev_fg`/`prev_bg`, ANSI, and OSC hyperlinks use Pi TUI visible-width semantics.
683
- `$all` deliberately includes enabled fill, so use `$all` only when that whole-catalog layout is intended.
684
- There is no `line_break` module; use literal newlines in `format`.
685
-
686
- ### 🔄 Cached refresh lifecycle
687
-
688
- Workspace, Git, and GitHub PR readers start only in TUI sessions and only for reachable enabled modules.
689
- Root format reachability, `$all`, module `disabled`, and module-format variables determine file and command requirements.
690
- Workspace/Git refreshes run at session start, after accepted settings, branch changes, tool/turn completion, and a 30-second fallback.
691
- GitHub PR uses the narrower lifecycle and 60-second network refresh described above.
692
- One read runs with at most one latest pending refresh.
693
- Immutable snapshot equality suppresses redraws, and session or request generations reject stale results.
694
- Shutdown, replacement, footer disposal, branch changes, and accepted settings abort active command work before starting replacements; disabling `github_pr` also stops its query and timers.
695
- Bounded local filesystem operations may finish, but stale generations cannot publish them.
696
- Execution identity is retained rather than re-read by the periodic fallback.
697
- Render and live preview consume snapshots synchronously and perform zero reads or commands.
698
-
699
- Missing, unreadable, malformed, oversized, timed-out, or unavailable sources produce empty values.
700
- Workspace and Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never recurse, and make no network calls.
701
- The native GitHub PR query is the documented network exception.
702
- The Cargo package lookup is the only ancestor walk and stops after eight parents.
103
+ Some opt-in modules read local development, deployment, cloud, host, or user metadata, run bounded local commands, or query GitHub through `gh`.
104
+ Review [Runtime and security](./skills/configuring-pi-starship/references/runtime-and-security.md) before enabling them.
703
105
 
704
106
  ## 🚧 Limitations
705
107
 
706
- - The formatter and modules are Starship-inspired, not fully compatible with Starship.
707
- - The extension does not load `starship.toml`, invoke the Starship binary, run custom shell modules, or provide unrestricted `env_var` behavior.
708
- - JVM/.NET, other long-tail languages, alternative version-control systems, system monitoring, and additional DevOps modules are not implemented.
709
- - Pi does not expose the auto-compaction toggle, so the footer cannot reliably show Pi's native `(auto)` marker.
108
+ pi-starship is Starship-inspired rather than fully compatible with shell Starship.
109
+ The complete supported and intentionally omitted behavior is documented in [Runtime and security](./skills/configuring-pi-starship/references/runtime-and-security.md).
710
110
 
711
111
  ## ➕ Adding a module
712
112
 
713
113
  Create `src/modules/<name>.ts` with its format variables, defaults, and runtime value resolver, then register it in display order in `src/modules/catalog.ts`.
714
114
  Configuration names, validation variables, defaults, and `$all` ordering are derived from that catalog.
715
115
  Add the module to the built-in root format only when it should be visible by default, then document and test its user-facing values.
716
-
717
116
  Keep `extension_status` last in the catalog so arbitrary third-party statuses follow native module output.
718
117
 
719
118
  ## 🗂️ Package layout
720
119
 
721
- - `dist/` — generated split TypeScript runtime loaded through Pi's Jiti loader.
722
- - `scripts/build-runtime.mjs` — deterministic runtime bundler and eager-boundary validator.
723
- - `src/index.ts` — thin authoritative source entrypoint.
724
- - `src/pi-starship.ts` — authoritative extension lifecycle, cached refresh binding, live preview, and footer.
725
- - `src/usage.ts` — native-aligned session usage and cache aggregation.
726
- - `src/command-contract.ts` — lightweight command routes and completions loaded at startup.
727
- - `src/commands.ts` — lazily loaded top-level menu, preview/confirmation workflows, and compatibility routes.
728
- - `src/command-configuration.ts` — nested configuration presentation, exact document views, and safe runtime-only disk reload.
729
- - `src/effective-config.ts` — explicit catalog-ordered public TOML projection and deterministic serialization.
730
- - `src/command-preset-picker.ts` — lifecycle-owned preset cursor and temporary footer-preview UI.
731
- - `src/presets/` — bundled complete TOML documents and stable preset metadata.
732
- - `src/command-inspector.ts` — adaptive Explain and searchable read-only module inspection surfaces.
733
- - `src/command-preview.ts` — adaptive, scrollable, keybinding-aware preview action surface.
734
- - `src/config.ts` — TOML loading, draft validation, defaults, atomic persistence, and rollback.
735
- - `src/format/` — native format/style parser and renderer.
736
- - `src/modules/` — domain module definitions, ordered registry, reachability, and width-aware renderer.
737
- - `src/modules/git/` — bounded local Git reader plus branch, status, and worktree modules.
738
- - `src/modules/github-pr.ts` — pure native GitHub PR snapshot presentation.
739
- - `src/runtime/github-pr.ts` — bounded `gh` query, validation, terminal-safe links, and expiry data.
740
- - `src/runtime/` — shared refresh controller and requirement-gated, lazily loaded package/language/context collectors.
120
+ ```text
121
+ packages/pi-starship/
122
+ ├── src/ # Modules, formats, presets, and runtime collectors
123
+ │ ├── index.ts # Thin Pi entrypoint
124
+ │ └── pi-starship.ts # Footer lifecycle and cached refresh
125
+ ├── dist/ # Generated Jiti runtime
126
+ ├── scripts/build-runtime.mjs # Runtime builder
127
+ ├── skills/configuring-pi-starship/ # Authoritative configuration skill and references
128
+ └── test/ # Behavior and lifecycle coverage
129
+ ```
130
+
131
+ The generated runtime is built from `src/index.ts` and does not import back into `src`.
741
132
 
742
133
  ## 🔎 Keywords
743
134
 
744
- Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, GitHub pull request, prompt cache, cache hit rate, Pi extension
135
+ Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, configuration editing, agent skill, GitHub pull request, prompt cache, cache hit rate, Pi extension
745
136
 
746
137
  ## 📄 License
747
138