@henryqw/pi-footer 5.1.0 → 5.1.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.
- package/README.md +56 -77
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# `@henryqw/pi-footer`
|
|
2
2
|
|
|
3
|
-
Keep footer identity, model usage, agent-work time, and extension status visible
|
|
3
|
+
Keep footer identity, model usage, agent-work time, and extension status visible in Pi. Use `/open` to open the current working directory. Enable the footer and open commands independently.
|
|
4
4
|
|
|
5
5
|
|
|
6
6
|
|
|
@@ -10,16 +10,16 @@ Keep footer identity, model usage, agent-work time, and extension status visible
|
|
|
10
10
|
pi install npm:@henryqw/pi-footer
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
This package replaces `@henryqw/pi-open-in`.
|
|
13
|
+
This package replaces `@henryqw/pi-open-in`. Remove that package before you upgrade to prevent duplicate `/open` and `/set-open-in` commands:
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
16
|
pi remove npm:@henryqw/pi-open-in
|
|
17
17
|
pi install npm:@henryqw/pi-footer
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
For project-local installations,
|
|
20
|
+
For project-local installations, add `--local` to both commands. Remove manually configured paths to the old package, then restart Pi. Keep the existing open command configuration at `config/pi-open-in/config.json`; do not move it.
|
|
21
21
|
|
|
22
|
-
Both entry points load by default. To
|
|
22
|
+
Both entry points load by default. To select only the open commands, use Pi's resource filter in `settings.json`:
|
|
23
23
|
|
|
24
24
|
```json
|
|
25
25
|
{
|
|
@@ -32,7 +32,7 @@ Both entry points load by default. To use `/open` without the custom footer, use
|
|
|
32
32
|
}
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
Select `extensions/footer.ts` for only the footer, or use `pi config` to toggle either resource. No package activation config is necessary.
|
|
36
36
|
|
|
37
37
|
## Works with
|
|
38
38
|
|
|
@@ -45,77 +45,64 @@ To use only the footer, select `extensions/footer.ts` instead. You can also use
|
|
|
45
45
|
|
|
46
46
|
## Use
|
|
47
47
|
|
|
48
|
-
|
|
48
|
+
Start a Pi TUI session to see the footer. Run `/open` to open the current directory in VS Code, even while the agent is busy.
|
|
49
49
|
|
|
50
50
|
| Surface | Type | Purpose |
|
|
51
51
|
| --- | --- | --- |
|
|
52
|
-
| Footer | ui | Shows footer identity, usage, model, agent-work time, and extension statuses. |
|
|
53
|
-
| `/open` | command | Opens the current
|
|
54
|
-
| `/set-open-in <command>` | command | Sets the command
|
|
52
|
+
| Footer | ui | Shows footer identity, usage, model, agent-work time, and extension statuses to the user. |
|
|
53
|
+
| `/open` | command | Opens the current directory for the user with the configured command. |
|
|
54
|
+
| `/set-open-in <command>` | command | Sets the user's open command, such as `cursor --reuse-window`. |
|
|
55
55
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
```text
|
|
59
|
-
pi-harness · clear-field-f8d2 [+2 ~3 ?1 ↑2] · PR #123 · approved Codex #1 · 50% · 7d 1d 1h 22m
|
|
60
|
-
↑ 12.4k · ↓ 2.1k · ↺ 84.3% · ⚡ 87.4 t/s · $ 0.127 · ◔ 36.8% gpt-5.6-luna • high
|
|
61
|
-
✓ CG · ● 🐴 ponytail: ⚡ FULL ◷ 12m 34s
|
|
62
|
-
```
|
|
56
|
+
`/open` runs `<command> <current-working-directory>`.
|
|
63
57
|
|
|
64
58
|
### Footer lines
|
|
65
59
|
|
|
66
|
-
|
|
60
|
+
| Line | Left | Right |
|
|
61
|
+
| --- | --- | --- |
|
|
62
|
+
| First | Repository, branch, Git state, and `pi-pr` pull-request status. Linked-worktree branches omit the generated `worktree/` prefix. | Non-empty `pi-multi-codex` family status. |
|
|
63
|
+
| Second: usage line | Input and output token totals, latest cache-hit rate, response throughput, estimated cost, and context use. | Active model and thinking level. |
|
|
64
|
+
| Third | CodeGraph first, then other extension statuses sorted by key, including Ponytail and `pi-rewind`. | Cumulative agent-work time. |
|
|
67
65
|
|
|
68
|
-
|
|
66
|
+
Token and cost totals include reported tool usage and completed `pi-subagent` background workflows. Response throughput measures output tokens per second from first to last streamed content. It excludes request latency, time to first token, and later provider work, including Claude bridge shutdown. Non-streamed or instantaneous responses show `—`. Other unavailable values show `—` without a percent sign.
|
|
69
67
|
|
|
70
|
-
|
|
68
|
+
Virtual models show the latest successful physical model and thinking level after an arrow: `auto • high → gpt-5.6-luna • medium`.
|
|
71
69
|
|
|
72
|
-
|
|
70
|
+
Thinking colors are dim grey for `off` and the model name, then green `minimal`, yellow-green `low`, lime `medium`, yellow `high`, orange `xhigh`, and red `max`. Active levels use ANSI-256 colors. `ultra` uses a rainbow only when the runtime supports it; unsupported levels do not appear.
|
|
73
71
|
|
|
74
|
-
|
|
72
|
+
CodeGraph shows `✓ CG` with an index, `○ CG` in Git without an index, and no index badge outside Git. Setup shows a dim spinner and elapsed time, such as `⠋ CG · indexing 8s`. Persistent failures retain their theme-colored `!` and error text. Direct `codegraph_explore` calls temporarily show `● CG`; queries inside scripted tools do not.
|
|
73
|
+
|
|
74
|
+
Other dependency statuses, such as `⠋ deps · installing 12s`, disappear after completion. Middle dots separate statuses. The footer preserves colors, links, glyphs, and interior spacing, trims outer whitespace, replaces line breaks with spaces, and shortens long statuses.
|
|
75
75
|
|
|
76
76
|
### Git state
|
|
77
77
|
|
|
78
|
-
|
|
78
|
+
Badges appear only when action is necessary:
|
|
79
79
|
|
|
80
80
|
| Badge | Meaning |
|
|
81
81
|
| --- | --- |
|
|
82
82
|
| `+2` | Two staged paths |
|
|
83
83
|
| `~3` | Three unstaged tracked paths |
|
|
84
|
-
| `?N` | `N` untracked porcelain status entries |
|
|
84
|
+
| `?N` | `N` untracked porcelain status entries; Git can collapse an untracked directory into one entry. |
|
|
85
85
|
| `!1` | One unresolved path |
|
|
86
|
-
| `↑2` | Two commits ahead of
|
|
87
|
-
| `↓1` | One commit behind
|
|
88
|
-
|
|
89
|
-
`?N` counts porcelain status entries. In `--untracked-files=normal` mode, Git can collapse a whole untracked directory to one entry.
|
|
90
|
-
|
|
91
|
-
Active operations appear first, such as `REBASE 3/7`, `MERGING`, or `CHERRY-PICKING`. Detached HEAD uses the short commit form `@a1b2c3d`.
|
|
92
|
-
|
|
93
|
-
The extension reads local Git data with `git status --porcelain=v2 --branch --untracked-files=normal`. It refreshes after each agent run and branch change. It does not make an LLM call or fetch a remote. Ahead and behind counts use the last fetched upstream state.
|
|
94
|
-
|
|
95
|
-
Unavailable values render as `—` without a misleading percent sign.
|
|
96
|
-
|
|
97
|
-
`off` uses the same dim grey as the model name. Active levels use an ANSI-256 gradient: green `minimal`, yellow-green `low`, lime `medium`, yellow `high`, orange `xhigh`, and red `max`.
|
|
98
|
-
|
|
99
|
-
`ultra` renders as a rainbow when the active Pi runtime supplies that thinking level. Unsupported levels never appear.
|
|
86
|
+
| `↑2` | Two commits ahead of upstream |
|
|
87
|
+
| `↓1` | One commit behind upstream |
|
|
100
88
|
|
|
101
|
-
|
|
89
|
+
Active operations appear first: `REBASE 3/7`, `MERGING`, or `CHERRY-PICKING`. Detached HEAD shows a short commit, such as `@a1b2c3d`.
|
|
102
90
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
Only direct `codegraph_explore` tool calls trigger the `● CG` badge. The footer does not show CodeGraph queries from inside scripted tools.
|
|
91
|
+
Local Git data comes from `git status --porcelain=v2 --branch --untracked-files=normal` and refreshes after agent runs and branch changes. No model call or remote fetch occurs. Ahead and behind counts use the last fetched upstream state.
|
|
106
92
|
|
|
107
93
|
## Config
|
|
108
94
|
|
|
109
|
-
Package-owned
|
|
95
|
+
Package-owned paths under `getAgentDir()` (normally `~/.pi/agent`):
|
|
96
|
+
|
|
97
|
+
- `~/.pi/agent/config/pi-footer/config.json`: footer colors.
|
|
98
|
+
- `~/.pi/agent/config/pi-open-in/config.json`: open command, retained from `pi-open-in`.
|
|
110
99
|
|
|
111
100
|
| Name | Description | Values | Default |
|
|
112
101
|
| --- | --- | --- | --- |
|
|
113
|
-
| `colors` |
|
|
114
|
-
| `command` | Command
|
|
115
|
-
|
|
116
|
-
The footer reads `colors` once at session start. Run `/reload` after you edit it. The footer never rewrites the file. A missing file or a missing role keeps the built-in color.
|
|
102
|
+
| `colors` | Footer-owned colors by role. | Object mapping roles to theme tokens, `#RGB`, `#RRGGBB`, `oklch(...)`, `okhsl(...)`, or ANSI indices `0` to `255`. | Built-in colors. |
|
|
103
|
+
| `command` | Command for `/open`. | Non-empty string. | `"code"` |
|
|
117
104
|
|
|
118
|
-
|
|
105
|
+
Colors load at session start; run `/reload` after edits. Missing files or roles keep built-in colors. Unknown keys, unknown roles, and invalid colors produce warnings with the path and reason. Invalid roles use built-in colors independently; malformed files use all built-in colors. The footer never rewrites the file.
|
|
119
106
|
|
|
120
107
|
### Footer color roles
|
|
121
108
|
|
|
@@ -123,14 +110,16 @@ Every role is optional:
|
|
|
123
110
|
|
|
124
111
|
| Role | Surface |
|
|
125
112
|
| --- | --- |
|
|
126
|
-
| `repository` | Repository name
|
|
127
|
-
| `branch` | Branch
|
|
128
|
-
| `gitStatus` | Git badges
|
|
129
|
-
| `input`, `output`, `cache`, `throughput`, `cost`, `context` | The six usage metrics
|
|
130
|
-
| `model` | Active
|
|
131
|
-
| `runtime` |
|
|
132
|
-
| `codegraphActive` |
|
|
133
|
-
| `separator` | Middle dots, bullets, arrows, and
|
|
113
|
+
| `repository` | Repository name. |
|
|
114
|
+
| `branch` | Branch name, with a hyperlink where supported. |
|
|
115
|
+
| `gitStatus` | Git badges. |
|
|
116
|
+
| `input`, `output`, `cache`, `throughput`, `cost`, `context` | The six usage metrics. |
|
|
117
|
+
| `model` | Active and physical models. |
|
|
118
|
+
| `runtime` | Agent-work time. |
|
|
119
|
+
| `codegraphActive` | Direct-call `● CG` badge. |
|
|
120
|
+
| `separator` | Middle dots, bullets, arrows, and truncation ellipsis. |
|
|
121
|
+
|
|
122
|
+
Theme tokens: `accent`, `dim`, `muted`, `text`, `success`, `warning`, `error`, and `thinkingText`. Colors do not change the thinking gradient or other extensions' status colors.
|
|
134
123
|
|
|
135
124
|
```json
|
|
136
125
|
{
|
|
@@ -152,17 +141,13 @@ Every role is optional:
|
|
|
152
141
|
}
|
|
153
142
|
```
|
|
154
143
|
|
|
155
|
-
Theme tokens are `accent`, `dim`, `muted`, `text`, `success`, `warning`, `error`, and `thinkingText`. Thinking levels keep their built-in gradient. Statuses from other extensions keep the colors from those extensions. The `colors` object controls neither.
|
|
156
|
-
|
|
157
144
|
### Open command
|
|
158
145
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
`/open` reads the config on every run. Only `/set-open-in` writes the file, atomically. Reads do not create or write the config home.
|
|
146
|
+
`/open` reads config on each run. Missing config silently uses `code`. Reads never create or write the config home; only `/set-open-in` writes the file, atomically.
|
|
162
147
|
|
|
163
148
|
## API
|
|
164
149
|
|
|
165
|
-
Consumers
|
|
150
|
+
Consumers must use the owner API, not read config directly. Replace `@henryqw/pi-open-in/open-uri` imports with `@henryqw/pi-footer/open-uri`:
|
|
166
151
|
|
|
167
152
|
```ts
|
|
168
153
|
import { loadOpenInConfig } from "@henryqw/pi-footer/open-uri";
|
|
@@ -171,29 +156,23 @@ const loaded = loadOpenInConfig();
|
|
|
171
156
|
if (loaded.status === "ok") console.log(loaded.value.command, loaded.issues);
|
|
172
157
|
```
|
|
173
158
|
|
|
174
|
-
These exports are for package consumers. The commands in Use are the Pi interfaces.
|
|
175
|
-
|
|
176
159
|
| Surface | Type | Purpose |
|
|
177
160
|
| --- | --- | --- |
|
|
178
|
-
| `default` (`openInExtension(pi)`) | function | Registers
|
|
179
|
-
| `OpenInConfig` | type | Describes the
|
|
180
|
-
| `loadOpenInConfig(agentDir?)` | function | Reads and validates
|
|
181
|
-
| `configuredOpenUri(path)` | function | Returns a safe VS Code URI for
|
|
161
|
+
| `default` (`openInExtension(pi)`) | function | Registers open commands without the footer. |
|
|
162
|
+
| `OpenInConfig` | type | Describes the command. |
|
|
163
|
+
| `loadOpenInConfig(agentDir?)` | function | Reads and validates owner config; accepts an optional agent directory. |
|
|
164
|
+
| `configuredOpenUri(path)` | function | Returns a safe VS Code URI for `code`, or `undefined` for other commands. |
|
|
182
165
|
|
|
183
|
-
`loadOpenInConfig` returns a `@henryqw/pi-config-store` `ConfigLoad
|
|
184
|
-
|
|
185
|
-
`configuredOpenUri(path)` works when the executable is `code`. With `code -n` or `code --new-window`, it adds `windowId=_blank` so the link opens in a new window. It returns `undefined` for other commands. An invalid config uses `code`. The function never shows a notification, because the footer calls it on each render. `@henryqw/pi-config-store` owns the config home and storage.
|
|
166
|
+
`loadOpenInConfig` returns a `@henryqw/pi-config-store` `ConfigLoad`: `status`, `source` (`"missing"` or `"file"`), `issues`, and `value` when `status` is `"ok"`. Invalid `value.command` gives `"code"` and an issue. Neither function shows notifications. `configuredOpenUri(path)` uses `code` for invalid config; `code -n` and `code --new-window` add `windowId=_blank`.
|
|
186
167
|
|
|
187
168
|
## Limits and recovery
|
|
188
169
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
An existing config file must be a JSON object with one non-empty string `command` property. An unknown key, an invalid `command`, or a malformed file shows a warning at session start, or at the next `/open`. The warning also shows when only the footer is active, because the footer link uses this config. Each issue shows one time in each session, even when the footer and `/open` are both active. The footer never shows a warning while it renders.
|
|
170
|
+
Open commands split on whitespace. Quoting and tokens with spaces are unsupported; use a wrapper script for executable paths with spaces.
|
|
192
171
|
|
|
193
|
-
|
|
172
|
+
Open config must be a JSON object with one non-empty string `command`. Unknown keys, invalid commands, or malformed files produce warnings at session start or the next `/open`, including footer-only installations. Each issue shows once per session, never during rendering. Invalid commands and malformed files use `code` without changing the file.
|
|
194
173
|
|
|
195
|
-
|
|
174
|
+
Fix config or run `/set-open-in <command>` to replace it; the command reports new issues before replacement. If the command fails, Pi reports its error output or exit code. Fix the command and retry `/open`.
|
|
196
175
|
|
|
197
|
-
|
|
176
|
+
With `code` and Pi hyperlink support, the accent-colored branch name links to the current path. `code -n` and `code --new-window` open a new window. Other executables or disabled hyperlinks give plain text.
|
|
198
177
|
|
|
199
|
-
Ghostty uses `Cmd+click`, but
|
|
178
|
+
Use primary click in Pi's default fullscreen TUI. Regular TUI (`"tuiMode": "regular"` or `--tui-mode regular`) needs terminal support for OSC 8 links and custom URI schemes. Ghostty uses `Cmd+click`, but might not open custom URI schemes.
|