@pi-unipi/footer 3.0.0-alpha.21 → 3.0.0-alpha.22

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 (2) hide show
  1. package/README.md +73 -116
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,147 +1,104 @@
1
- # @pi-unipi/footer
1
+ # Footer
2
2
 
3
- Persistent status bar at the bottom of the terminal. Shows live stats from all Unipi packages — compactor tokens saved, memory count, MCP status, Ralph loops, workflow state, kanboard tasks, notifications.
3
+ Show live session stats and the state of every UniPi package at the bottom of the terminal.
4
4
 
5
- Subscribes to events from every package and renders segments using Pi's `setFooter` + `setWidget` APIs. Responsive layout adjusts to terminal width, with a secondary row for narrow terminals.
5
+ `@pi-unipi/footer` · part of [UniPi](../../README.md)
6
6
 
7
- ## Glance Footer (new in 2.12)
7
+ ![Glance footer: a framed input box with the branch, model and a session stats line](../../docs/assets/screenshots/glance-footer.png)
8
8
 
9
- An experimental input surface, on by default and toggleable in `/unipi:settings` (Footer) → **Glance mode**:
9
+ ## What it does
10
10
 
11
+ - Puts a frame around the input box. This is **glance mode**, and it is on by default.
12
+ - Shows a stats line below the input. It shows turns, steps, model time and tool time. It also shows average time to first token (TTFT), tokens per second, compactions and cache hit rate.
13
+ - Shows a line above the input with counts of background tasks: running, stopped, failed and done.
14
+ - Shows a status line with segments from each package when glance mode is off. This is the **classic** footer.
15
+ - Lets you select a preset, separator, icon style and color mode, and turn each segment on or off.
16
+
17
+ ## Quick start
18
+
19
+ UniPi installs this package:
20
+
21
+ ```bash
22
+ pi install npm:@pi-unipi/unipi
11
23
  ```
12
- ╭─ 󰚩 UNIPI │ feat/footer-default-v2 │ ───────────────────────────╮
13
- │ Type your prompt here... │
14
- ╰─ 󰉋 unipi ────────────────────── 42%/1.0M │ GLM-5.3 │ thinking:high ─╯
15
- 2 turn · 20 steps | 00:12:14 · tool 00:02 | 20ms avg ttft · 120 tok/s | 90% cache hit
24
+
25
+ To install this package alone:
26
+
27
+ ```bash
28
+ pi install npm:@pi-unipi/footer
16
29
  ```
17
30
 
18
- - **Top border:** animated lolcat-gradient UNIPI brand + git branch (turns rainbow-frame animated while thinking is max/xhigh)
19
- - **Bottom border:** workspace · context %/window · model · thinking level
20
- - **Session strip:** turns/steps, wall + tool wall time, average TTFT, tok/s, cache hit % — colored per stat, honest across restarts (derived from persisted session timestamps when live hooks are unavailable; provider-reported `usage.output` anchors token counts whenever present)
21
- - **Process line (new in 2.13):** centered one-liner directly above the frame while background work is in flight — `● 3 running ● 1 stopped ● 1 failed ● 2 done` — green ● running, yellow ● stopped (killed), red ● failed, gray ● done. Covers every task type (shell jobs, delegates, fusion workflows) via direct registry reads; zero-count buckets are omitted and the line hides when idle. Counts reset per session.
22
- - The classic segment status line is suppressed while glance mode is on; toggle it back for the classic footer
31
+ The footer starts with the session. Open `/unipi:settings` → **Footer** to change it.
23
32
 
24
33
  ## Commands
25
34
 
26
- | Command | Description |
27
- |---------|-------------|
28
- | `/unipi:footer` | Toggle footer on/off |
29
- | `/unipi:footer on` / `/unipi:footer off` | Enable/disable explicitly |
30
- | `/unipi:settings` | Hub — preset, separator, zone separator, icon style, glance mode, per-segment toggles (Footer group) |
31
- | `/unipi:footer-help` | Show footer segment guide |
35
+ | Command | What it does |
36
+ |---|---|
37
+ | `/unipi:footer` | Turns the footer on or off. |
38
+ | `/unipi:footer on` | Turns the footer on. |
39
+ | `/unipi:footer off` | Turns the footer off. |
40
+ | `/unipi:footer-help` | Shows each active segment with its icon, label and description. |
32
41
 
33
- ## Special Triggers
42
+ ## The glance frame
34
43
 
35
- Footer subscribes to events from every Unipi package:
44
+ The glance frame has three parts:
36
45
 
37
- | Group | Events | Segments |
38
- |-------|--------|----------|
39
- | core | Pi SDK | model, thinking, path, git, context_pct, cost, tokens, session |
40
- | compactor | Pi session data | compactions — `cmp 4× 39k→13k · 3m` (count, tokens before → after, time since the last; hidden until the first) |
41
- | memory | `MEMORY_STORED`/`DELETED`/`CONSOLIDATED` | project_count, total_count, consolidations |
42
- | mcp | `MCP_SERVER_STARTED`/`STOPPED`/`ERROR` | servers_total, servers_active, tools_total |
43
- | ralph | `RALPH_LOOP_START`/`END`/`ITERATION_DONE` | active_loops, total_iterations, loop_status |
44
- | workflow | `WORKFLOW_START`/`END` | current_command, sandbox_level, command_duration |
45
- | kanboard | Direct registry read | docs_count, tasks_done, tasks_total, task_pct |
46
- | notify | `NOTIFICATION_SENT` | platforms_enabled, last_sent |
46
+ - **Top border.** The UNIPI brand, the long-horizon mode, the git branch, and the plan and permission mode. The brand shows a moving rainbow. The frame also shows the rainbow when the thinking level is `xhigh` or `max`.
47
+ - **Bottom border.** The workspace name, context use and window size, the model and the thinking level. With a [Fusion](../fusion/README.md) pair, it shows the lead and the sidekick. It also shows Kanboard claims.
48
+ - **Stats line.** The line below the input. A part stays hidden until it has data. For example, compactions show only after the first compaction.
47
49
 
48
- Footer works even if packages load after it — late-arriving events update the cache.
50
+ The background-task line reads the [Background Tasks](../background-tasks/README.md) registry. It shows nothing when no task exists.
51
+
52
+ Set **Glance mode** to off to get the classic status line.
49
53
 
50
54
  ## Presets
51
55
 
52
- | Preset | Description |
53
- |--------|-------------|
54
- | `default` | Glance-era: UNIPI brand, model, thinking, directory, git \| context/tokens, tps, cost, clock |
55
- | `classic` | The pre-2.12 balanced layout: model, api, tools, git \| tps, context, cost + compactor + memory + ralph |
56
- | `minimal` | Essentials only: path, git, context |
57
- | `compact` | Core + key stats: model, git, cost, context |
58
- | `full` | Everything from all groups |
59
- | `ascii` | Core segments with ASCII icons |
60
-
61
- ## Segment Groups
62
-
63
- | Group | Default | Data Source |
64
- |-------|---------|-------------|
65
- | **core** | ON | Pi SDK (ctx.sessionManager, footerData) |
66
- | **compactor** | ON | Live Pi session data; last-compaction event |
67
- | **memory** | ON | `MEMORY_STORED`/`DELETED`/`CONSOLIDATED` events |
68
- | **mcp** | ON | `MCP_SERVER_STARTED`/`STOPPED`/`ERROR` events |
69
- | **ralph** | ON | `RALPH_LOOP_START`/`END`/`ITERATION_DONE` events |
70
- | **workflow** | ON | `WORKFLOW_START`/`END` events |
71
- | **kanboard** | ON | Kanboard registry (direct read) |
72
- | **notify** | OFF | `NOTIFICATION_SENT` event |
73
- | **status_ext** | ON | `footerData.getExtensionStatuses()` |
74
-
75
- ## Configurables
76
-
77
- Settings in `~/.pi/agent/settings.json` under `unipi.footer`:
78
-
79
- ```json
80
- {
81
- "unipi": {
82
- "footer": {
83
- "enabled": true,
84
- "preset": "default",
85
- "glanceMode": true,
86
- "separator": "powerline-thin",
87
- "iconStyle": "nerd",
88
- "colorMode": "auto",
89
- "groups": {
90
- "compactor": {
91
- "show": true,
92
- "segments": {
93
- "compactions": true
94
- }
95
- }
96
- }
97
- }
98
- }
99
- }
100
- ```
56
+ A preset selects the segments of the classic status line.
101
57
 
102
- ### Separator Styles
58
+ | Preset | Segments |
59
+ |---|---|
60
+ | `default` | brand, mode, model, directory, git, context, compactions, tokens, TPS, cost, clock, duration |
61
+ | `classic` | mode, model, API state, tool count, git, TPS, context, cost, compactions, memory, command, loop status, extensions |
62
+ | `minimal` | mode, model, git, context, clock |
63
+ | `compact` | mode, model, git, TPS, context, cost, clock, duration |
64
+ | `full` | all groups, with a second row |
65
+ | `ascii` | the same segments as `compact` |
103
66
 
104
- | Style | Look |
105
- |-------|------|
106
- | `powerline` | Thick powerline arrows |
107
- | `powerline-thin` | Thin powerline arrows (default) |
108
- | `slash` | / |
109
- | `pipe` | \| |
110
- | `dot` | Middle dot |
111
- | `ascii` | > < |
67
+ The hub list also shows `dense`, `devops` and `zen`. These names have no preset definition, so the footer uses `default` for them. To select `compact`, `full` or `ascii`, edit the settings file.
112
68
 
113
- ### Icon Styles
69
+ ## Settings
114
70
 
115
- | Style | Description |
116
- |-------|-------------|
117
- | `nerd` | Nerd Font glyphs (auto-detected) |
118
- | `emoji` | Unicode symbols (works on most terminals) |
119
- | `text` | Plain text labels (works everywhere). Glance frame drops the robot glyph: `UNIPI │ branch:main`, `workspace:unipi` |
71
+ Open `/unipi:settings` → **Footer**. The file is `~/.unipi/config/footer/config.json`. A project file at `.unipi/config/footer/config.json` overrides it.
120
72
 
121
- When `iconStyle` is not set, footer auto-detects Nerd Font support and defaults to `nerd` if available, `emoji` otherwise.
73
+ | Key | Default | What it does |
74
+ |---|---|---|
75
+ | `enabled` | `true` | Turns the footer on or off. |
76
+ | `glanceMode` | `true` | Uses the glance frame around the input. |
77
+ | `preset` | `default` | Selects the segments of the classic status line. |
78
+ | `showFullLabels` | `false` | Shows full labels in place of short labels. |
79
+ | `separator` | `powerline-thin` | Segment divider: `powerline`, `powerline-thin`, `slash`, `pipe`, `dot`, `ascii`. |
80
+ | `zoneSeparator` | `│` | Divider between the left, center and right zones. |
81
+ | `iconStyle` | `nerd` | Icon set: `nerd` (needs a Nerd Font), `emoji` or `text`. |
82
+ | `colorMode` | `auto` | `auto`, `truecolor`, `256` or `none`. |
83
+ | `groups.<group>.show` | `true` (`notify`: `false`) | Shows or hides a segment group. |
84
+ | `groups.<group>.segments.<id>` | per segment | Shows or hides one segment. |
122
85
 
123
- ### Color Mode
86
+ `colorMode: auto` uses 24-bit color where the terminal supports it. It uses 256 colors in terminals such as Apple Terminal. It uses no color when the `NO_COLOR` environment variable exists.
124
87
 
125
- | Mode | Description |
126
- |------|-------------|
127
- | `auto` | Detect terminal support from environment (default) |
128
- | `truecolor` | Force 24-bit ANSI color |
129
- | `256` | Force xterm-256 color fallback |
130
- | `none` | Disable footer color escapes |
88
+ The hub **Color mode** list shows `mono`. The footer does not know this value and uses `auto`. Use `none` in the file to turn off color.
131
89
 
132
- `auto` uses truecolor where supported and downgrades to xterm-256 colors for terminals such as Apple Terminal that do not reliably render 24-bit color escapes.
90
+ For the full list of segments and icons, refer to [Footer customization](../../FOOTER_CUSTOMIZATION.md).
133
91
 
134
- ### Responsive Layout
92
+ ## How it works
135
93
 
136
- ```
137
- Wide terminal (>120 cols):
138
- model | thinking | path | git | context | compactions | cost | project_count
94
+ The footer listens to UniPi events on the [event bus](../../docs/architecture/event-bus.md). Examples are `MEMORY_STORED`, `MCP_SERVER_STARTED`, `RALPH_LOOP_START`, `WORKFLOW_START`, `COMPACTOR_COMPACTED` and `NOTIFICATION_SENT`. It keeps the last data of each event. Thus a package that loads after the footer still shows its data.
139
95
 
140
- Narrow terminal (<120 cols):
141
- Row 1: model | thinking | path | git | context | cost
142
- Row 2: compactions | project_count | ralph | workflow
143
- ```
96
+ Some segments read data directly: the Pi session, the Kanboard registry and the Info Screen cache. The footer draws again each second.
97
+
98
+ The classic status line puts segments that do not fit into a second row.
144
99
 
145
- ## License
100
+ ## See also
146
101
 
147
- MIT
102
+ - [Footer customization](../../FOOTER_CUSTOMIZATION.md)
103
+ - [Info Screen](../info-screen/README.md)
104
+ - [Settings reference](../../docs/reference/settings.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/footer",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
5
5
  "type": "module",
6
6
  "main": "index.ts",
@@ -32,8 +32,8 @@
32
32
  "access": "public"
33
33
  },
34
34
  "dependencies": {
35
- "@pi-unipi/core": "3.0.0-alpha.21",
36
- "@pi-unipi/background-tasks": "3.0.0-alpha.21"
35
+ "@pi-unipi/core": "3.0.0-alpha.22",
36
+ "@pi-unipi/background-tasks": "3.0.0-alpha.22"
37
37
  },
38
38
  "peerDependencies": {
39
39
  "@earendil-works/pi-coding-agent": "^0.87.1",