@narumitw/pi-starship 0.52.3 → 0.55.0

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