@neilurk12/pi-clean-footer 0.1.0

package/docs/superpowers/specs/2026-05-09-clean-footer-extension-design.md

@@ -0,0 +1,149 @@
+# Clean Footer Extension Design
+
+## Goal
+
+Create a project-local pi footer extension that replaces the built-in footer with a cleaner, adaptive footer focused on model identity, reasoning effort, project context, git state, context usage, and cumulative token/cache telemetry.
+
+## Placement
+
+Use a project-local extension:
+
+```text
+.pi/extensions/clean-footer/index.ts
+```
+
+This keeps development local to the current repo and supports hot reload through `/reload`. The extension should have no runtime dependencies beyond pi's extension/TUI APIs unless implementation proves a helper is necessary.
+
+## Footer Layout
+
+The footer is split into left and right regions with adaptive spacing.
+
+Left side:
+
+```text
+model • effort | dir | branch ●N
+```
+
+Right side:
+
+```text
+ctx used/max | ↑input ↓output Σtotal ↯cacheRead ↥cacheWrite
+```
+
+Example full-width render:
+
+```text
+sonnet-4.5 • high | footer | main ●3          ctx 84k/200k | ↑12.4k ↓3.1k Σ15.5k ↯8.2k ↥1.0k
+```
+
+## Field Semantics
+
+### Model and effort
+
+- Display a smart-short model name when known, with pattern-based shortening for common model IDs.
+- Fallback to truncated exact model ID when no smart rule matches.
+- Display reasoning effort directly beside model name as `low`, `med`, `high`, or `xhigh`.
+- Format: `model • effort`.
+
+### Directory
+
+- Display only the basename of `ctx.cwd`.
+- Do not show parent path or full path.
+
+### Git
+
+- Hide git segment entirely outside a git repository.
+- Inside a repo, display branch plus dirty count.
+- Dirty count is the number of lines from `git status --porcelain`, including untracked files.
+- Format: `branch ●N` when dirty, `branch` when clean.
+- Git refresh is event-driven and debounced, not run on every render.
+
+### Context usage
+
+- Display used/max tokens: `ctx 84k/200k`.
+- If max context is unknown, display `ctx 84k/--`.
+- Color thresholds:
+  - below 70%: normal
+  - 70% through 84%: warning/yellow
+  - 85% and above: danger/red
+  - unknown max: dim/neutral
+
+### Token and cache telemetry
+
+- Use cumulative totals across the active session branch.
+- Display input, output, total, cache read, and cache write.
+- Format: `↑12k ↓3k Σ15k ↯8k ↥1k`.
+
+## Adaptive Width Tiers
+
+The footer must degrade gracefully as terminal width shrinks.
+
+1. Full: model/effort, directory, git, context used/max, input/output/total/cache read/cache write.
+2. Medium: hide cache read/write.
+3. Small: hide input/output breakdown and show total only.
+4. Tiny: show left side plus context only.
+5. Minimum: show model and context only.
+
+Truncation should prefer preserving meaningful whole segments rather than cramming all fields.
+
+## Refresh and Invalidation
+
+- Install footer on `session_start` when `ctx.hasUI` is true.
+- Request render on relevant events, without a periodic timer.
+- Refresh git state:
+  - at startup/reload
+  - after tool executions that may affect files: `bash`, `edit`, `write`
+  - after user `!`/`!!` bash commands
+- Debounce git refresh by roughly 500 ms.
+- Do not execute git commands from footer `render()`.
+
+## Commands
+
+Register `/footer` command behavior:
+
+- `/footer`: toggle custom footer on/off.
+- `/footer refresh`: force git refresh and re-render.
+
+The footer should be enabled by default when the extension loads in an interactive UI.
+
+## Non-Interactive Behavior
+
+If `ctx.hasUI` is false, the extension should silently no-op for footer setup and avoid throwing. Commands should also avoid crashing in non-interactive, RPC, print, or JSON contexts.
+
+## Style
+
+Use color-coded segments, but keep colors restrained and theme-driven:
+
+- model/effort: accent-like color
+- directory: dim/muted
+- git branch: success/green-ish; dirty marker/count: warning/accent
+- context: threshold-based normal/warning/danger
+- tokens/cache: muted/info style
+
+## Error Handling
+
+- Git command failures should clear/hide git state rather than displaying errors in footer.
+- Missing model/context metadata should use documented fallbacks.
+- Extension reload should restore built-in footer when disabled or on cleanup if necessary.
+
+## Testing Strategy
+
+Manual checks:
+
+1. Load extension with `/reload` and verify footer replaces built-in footer.
+2. Toggle with `/footer`.
+3. Force refresh with `/footer refresh`.
+4. Verify basename directory display.
+5. Verify git branch and dirty count update after file edits and bash changes.
+6. Verify git segment hides outside a repo.
+7. Verify context/token fields update after assistant responses.
+8. Resize terminal to exercise all width tiers.
+9. Run in non-interactive mode or no-UI context if available and confirm no crash.
+
+## Out of Scope
+
+- Persistent user config file.
+- NPM package publishing.
+- Provider-specific exhaustive model alias registry.
+- Polling-based live refresh.
+- Full git status counts or untracked split counts.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@neilurk12/pi-clean-footer",
+  "version": "0.1.0",
+  "description": "Clean adaptive footer extension for pi coding agent.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "footer",
+    "terminal"
+  ],
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}