@henryqw/pi-footer 5.1.0 → 5.1.2
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 +54 -86
- 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. Enable the footer and open commands independently.
|
|
4
4
|
|
|
5
5
|
|
|
6
6
|
|
|
@@ -10,16 +10,7 @@ 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
|
-
|
|
14
|
-
|
|
15
|
-
```bash
|
|
16
|
-
pi remove npm:@henryqw/pi-open-in
|
|
17
|
-
pi install npm:@henryqw/pi-footer
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
For project-local installations, use `--local` on both commands. Also remove manually configured paths to the old package. Then restart Pi. The existing open command configuration stays at `config/pi-open-in/config.json`. Do not move it.
|
|
21
|
-
|
|
22
|
-
Both entry points load by default. To use `/open` without the custom footer, use Pi's native package resource filter in `settings.json`:
|
|
13
|
+
Both entry points load by default. To select only the open commands, use Pi's resource filter in `settings.json`:
|
|
23
14
|
|
|
24
15
|
```json
|
|
25
16
|
{
|
|
@@ -32,7 +23,7 @@ Both entry points load by default. To use `/open` without the custom footer, use
|
|
|
32
23
|
}
|
|
33
24
|
```
|
|
34
25
|
|
|
35
|
-
|
|
26
|
+
Select `extensions/footer.ts` for only the footer, or use `pi config` to toggle either resource.
|
|
36
27
|
|
|
37
28
|
## Works with
|
|
38
29
|
|
|
@@ -45,77 +36,64 @@ To use only the footer, select `extensions/footer.ts` instead. You can also use
|
|
|
45
36
|
|
|
46
37
|
## Use
|
|
47
38
|
|
|
48
|
-
|
|
39
|
+
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
40
|
|
|
50
41
|
| Surface | Type | Purpose |
|
|
51
42
|
| --- | --- | --- |
|
|
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
|
|
43
|
+
| Footer | ui | Shows footer identity, usage, model, agent-work time, and extension statuses to the user. |
|
|
44
|
+
| `/open` | command | Opens the current directory for the user with the configured command. |
|
|
45
|
+
| `/set-open-in <command>` | command | Sets the user's open command, such as `cursor --reuse-window`. |
|
|
55
46
|
|
|
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
|
-
```
|
|
47
|
+
`/open` runs `<command> <current-working-directory>`.
|
|
63
48
|
|
|
64
49
|
### Footer lines
|
|
65
50
|
|
|
66
|
-
|
|
51
|
+
| Line | Left | Right |
|
|
52
|
+
| --- | --- | --- |
|
|
53
|
+
| 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. |
|
|
54
|
+
| Second: usage line | Input and output token totals, latest cache-hit rate, response throughput, estimated cost, and context use. | Active model and thinking level. |
|
|
55
|
+
| Third | CodeGraph first, then other extension statuses sorted by key, including Ponytail and `pi-rewind`. | Cumulative agent-work time. |
|
|
56
|
+
|
|
57
|
+
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.
|
|
67
58
|
|
|
68
|
-
|
|
59
|
+
Virtual models show the latest successful physical model and thinking level after an arrow: `auto • high → gpt-5.6-luna • medium`.
|
|
69
60
|
|
|
70
|
-
|
|
61
|
+
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.
|
|
71
62
|
|
|
72
|
-
|
|
63
|
+
For CodeGraph badges, see [`@henryqw/pi-codegraph`](https://pi.henry.wang/extensions/pi-codegraph).
|
|
73
64
|
|
|
74
|
-
|
|
65
|
+
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
66
|
|
|
76
67
|
### Git state
|
|
77
68
|
|
|
78
|
-
|
|
69
|
+
Badges appear only when action is necessary:
|
|
79
70
|
|
|
80
71
|
| Badge | Meaning |
|
|
81
72
|
| --- | --- |
|
|
82
73
|
| `+2` | Two staged paths |
|
|
83
74
|
| `~3` | Three unstaged tracked paths |
|
|
84
|
-
| `?N` | `N` untracked porcelain status entries |
|
|
75
|
+
| `?N` | `N` untracked porcelain status entries; Git can collapse an untracked directory into one entry. |
|
|
85
76
|
| `!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.
|
|
77
|
+
| `↑2` | Two commits ahead of upstream |
|
|
78
|
+
| `↓1` | One commit behind upstream |
|
|
94
79
|
|
|
95
|
-
|
|
80
|
+
Active operations appear first: `REBASE 3/7`, `MERGING`, or `CHERRY-PICKING`. Detached HEAD shows a short commit, such as `@a1b2c3d`.
|
|
96
81
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
`ultra` renders as a rainbow when the active Pi runtime supplies that thinking level. Unsupported levels never appear.
|
|
100
|
-
|
|
101
|
-
Only the non-empty `pi-multi-codex` quota status occupies the right side of the first line. The `pi-pr` pull-request status stays beside footer identity. CodeGraph index status, setup progress, or tool activity appears separately on the third line.
|
|
102
|
-
|
|
103
|
-
Statuses from other extensions, including Ponytail and `pi-rewind`, share the left side of the third line. The footer sorts these statuses by key. It preserves colors, links, glyphs, and interior spacing. It removes leading and trailing whitespace and changes line breaks to spaces. It can shorten long statuses to fit the footer.
|
|
104
|
-
|
|
105
|
-
Only direct `codegraph_explore` tool calls trigger the `● CG` badge. The footer does not show CodeGraph queries from inside scripted tools.
|
|
82
|
+
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
83
|
|
|
107
84
|
## Config
|
|
108
85
|
|
|
109
|
-
Package-owned
|
|
86
|
+
Package-owned paths under `getAgentDir()` (normally `~/.pi/agent`):
|
|
87
|
+
|
|
88
|
+
- `~/.pi/agent/config/pi-footer/config.json`: footer colors.
|
|
89
|
+
- `~/.pi/agent/config/pi-open-in/config.json`: open command.
|
|
110
90
|
|
|
111
91
|
| Name | Description | Values | Default |
|
|
112
92
|
| --- | --- | --- | --- |
|
|
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.
|
|
93
|
+
| `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. |
|
|
94
|
+
| `command` | Command for `/open`. | Non-empty string. | `"code"` |
|
|
117
95
|
|
|
118
|
-
|
|
96
|
+
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
97
|
|
|
120
98
|
### Footer color roles
|
|
121
99
|
|
|
@@ -123,14 +101,16 @@ Every role is optional:
|
|
|
123
101
|
|
|
124
102
|
| Role | Surface |
|
|
125
103
|
| --- | --- |
|
|
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
|
|
104
|
+
| `repository` | Repository name. |
|
|
105
|
+
| `branch` | Branch name, with a hyperlink where supported. |
|
|
106
|
+
| `gitStatus` | Git badges. |
|
|
107
|
+
| `input`, `output`, `cache`, `throughput`, `cost`, `context` | The six usage metrics. |
|
|
108
|
+
| `model` | Active and physical models. |
|
|
109
|
+
| `runtime` | Agent-work time. |
|
|
110
|
+
| `codegraphActive` | Direct-call `● CG` badge. |
|
|
111
|
+
| `separator` | Middle dots, bullets, arrows, and truncation ellipsis. |
|
|
112
|
+
|
|
113
|
+
Theme tokens: `accent`, `dim`, `muted`, `text`, `success`, `warning`, `error`, and `thinkingText`. Colors do not change the thinking gradient or other extensions' status colors.
|
|
134
114
|
|
|
135
115
|
```json
|
|
136
116
|
{
|
|
@@ -152,17 +132,9 @@ Every role is optional:
|
|
|
152
132
|
}
|
|
153
133
|
```
|
|
154
134
|
|
|
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
|
-
### Open command
|
|
158
|
-
|
|
159
|
-
A missing file silently uses the default command, `code`. An invalid existing file shows a warning and uses `code`. The file stays unchanged. See Limits and recovery.
|
|
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.
|
|
162
|
-
|
|
163
135
|
## API
|
|
164
136
|
|
|
165
|
-
Consumers
|
|
137
|
+
Consumers must use the owner API, not read config directly:
|
|
166
138
|
|
|
167
139
|
```ts
|
|
168
140
|
import { loadOpenInConfig } from "@henryqw/pi-footer/open-uri";
|
|
@@ -171,29 +143,25 @@ const loaded = loadOpenInConfig();
|
|
|
171
143
|
if (loaded.status === "ok") console.log(loaded.value.command, loaded.issues);
|
|
172
144
|
```
|
|
173
145
|
|
|
174
|
-
These exports are for package consumers. The commands in Use are the Pi interfaces.
|
|
175
|
-
|
|
176
146
|
| Surface | Type | Purpose |
|
|
177
147
|
| --- | --- | --- |
|
|
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
|
|
182
|
-
|
|
183
|
-
`loadOpenInConfig` returns a `@henryqw/pi-config-store` `ConfigLoad` result: `status`, `source` (`"missing"` or `"file"`), `issues`, and, when `status` is `"ok"`, `value`. The function validates `value.command`. An invalid `command` gives `"code"` and an issue. The function does not show issues. Pass an agent directory when needed.
|
|
148
|
+
| `default` (`openInExtension(pi)`) | function | Registers open commands without the footer. |
|
|
149
|
+
| `OpenInConfig` | type | Describes the command. |
|
|
150
|
+
| `loadOpenInConfig(agentDir?)` | function | Reads and validates owner config; accepts an optional agent directory. |
|
|
151
|
+
| `configuredOpenUri(path)` | function | Returns a safe VS Code URI for `code`, or `undefined` for other commands. |
|
|
184
152
|
|
|
185
|
-
`
|
|
153
|
+
`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
154
|
|
|
187
155
|
## Limits and recovery
|
|
188
156
|
|
|
189
|
-
|
|
157
|
+
Open commands split on whitespace. Quoting and tokens with spaces are unsupported; use a wrapper script for executable paths with spaces.
|
|
190
158
|
|
|
191
|
-
|
|
159
|
+
`/open` reads config on each run. Missing config silently uses `code`. Only `/set-open-in` writes the file, atomically.
|
|
192
160
|
|
|
193
|
-
|
|
161
|
+
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
162
|
|
|
195
|
-
|
|
163
|
+
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
164
|
|
|
197
|
-
|
|
165
|
+
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
166
|
|
|
199
|
-
Ghostty uses `Cmd+click`, but
|
|
167
|
+
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.
|