---
status: resolved
parent: "[[057-pi-ui-customization-map]]"
blocked-by: []
resolved-at: "2026-07-31T23:58:11-04:00"
tags:
  - ticket/research
---

# Pi TUI layout customization research

## Question

What can Pi extensions change about the prompt-area layout, footer, widgets above or below the editor, working indicator, and editor chrome, and can the current below-prompt information be consolidated into a status bar above the text prompt without patching Pi itself?

## Findings

Pi extensions can replace the built-in footer without patching Pi.
The TUI docs describe `ctx.ui.setFooter((tui, theme, footerData) => component)` as the custom-footer API and state that it replaces the footer, while `ctx.ui.setFooter(undefined)` restores the built-in footer.
The implementation confirms the replacement behavior: `setExtensionFooter` removes either the existing custom footer or built-in footer from the UI, creates the custom footer from the factory, and adds it to the UI.
The same implementation restores the built-in footer when the factory is undefined.
Sources: `docs/tui.md` section “Pattern 6: Custom Footer”; `docs/extensions.md` section “Widgets, Status, and Footer”; `dist/modes/interactive/interactive-mode.js` `setExtensionFooter`.

Pi extensions can add persistent widgets above the editor or below the editor.
The documented `ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"])` call places a widget above the editor by default, and `ctx.ui.setWidget(..., { placement: "belowEditor" })` places it below the editor.
The shipped `widget-placement.ts` example uses exactly those two calls on `session_start`.
This gives an extension-supported way to put a custom status bar directly above the text prompt.
Sources: `docs/tui.md` section “Pattern 5: Widgets Above/Below Editor”; `docs/extensions.md` section “Widgets, Status, and Footer”; `examples/extensions/widget-placement.ts`.

Pi extensions can customize the working indicator and working visibility.
The docs expose `ctx.ui.setWorkingMessage`, `ctx.ui.setWorkingVisible`, and `ctx.ui.setWorkingIndicator`.
This can reduce or alter the streaming “working” chrome, but it only affects the streaming loader row and indicator, not the entire prompt layout.
Sources: `docs/extensions.md` section “Widgets, Status, and Footer”; `docs/tui.md` section “Pattern 4b: Working Indicator Customization”; `examples/extensions/working-indicator.ts`.

Pi extensions can replace the editor component, but that is a more invasive path.
The TUI docs describe a `CustomEditor` pattern and advise extending `CustomEditor` rather than the base `Editor` to preserve app keybindings such as escape-to-abort, ctrl-d, and model switching.
The extensions docs list `modal-editor.ts` as the example for `setEditorComponent`.
The implementation exposes `setEditorComponent` and `getEditorComponent` in the extension UI context.
This means editor replacement is possible if footer plus above-editor widget does not remove enough dead space, but it should not be the first prototype.
Sources: `docs/tui.md` section “Pattern 7: Custom Editor”; `docs/extensions.md` examples reference; `dist/modes/interactive/interactive-mode.js` extension UI context.

Pi has a `setHeader` API in the implementation and a shipped `custom-header.ts` example, but the docs describe it as replacing the startup header rather than the prompt-area footer.
It is not the right primary hook for moving footer information above the prompt.
Sources: `examples/extensions/custom-header.ts`; `docs/extensions.md` examples reference; `dist/modes/interactive/interactive-mode.js` `setExtensionHeader`.

The built-in footer currently owns exactly the information the user wants to consolidate: cwd plus branch and session name, session usage totals, context usage, model, thinking level, and extension statuses.
The implementation constructs a `pwdLine`, a stats/model line, and an optional extension-status line.
The footer data provider exposes git branch and extension statuses to custom footers, while token stats and model info are expected to come from the session context and model.
Sources: `dist/modes/interactive/components/footer.js`; `dist/core/footer-data-provider.js`; `examples/extensions/custom-footer.ts`.

## Answer

Yes, the target customization can be prototyped without patching Pi.
The most promising extension-only design is:

1. Replace the built-in footer with a minimal or empty custom footer to remove below-prompt lines.
2. Add a one-line widget above the editor to show cwd, branch, context usage, model, and thinking level.
3. Customize or hide the working indicator only if the working row contributes meaningful dead space during streaming.
4. Avoid editor replacement unless the footer-plus-widget prototype proves insufficient.

## Limitations

The docs and implementation establish that a widget can be placed above the editor and that the footer can be replaced.
They do not prove the exact visual result will feel good in the live TUI.
That needs the HITL prototype ticket.

The footer APIs can replace the footer, but they do not literally move the built-in footer component above the editor.
The extension must recreate the desired data presentation in its own widget or custom footer.

## Citations

- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/tui.md`, sections “Pattern 5: Widgets Above/Below Editor”, “Pattern 6: Custom Footer”, and “Pattern 7: Custom Editor”.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`, section “Widgets, Status, and Footer” and examples reference table.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/widget-placement.ts`.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/custom-footer.ts`.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/custom-header.ts`.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/modes/interactive/interactive-mode.js`.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/modes/interactive/components/footer.js`.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/core/footer-data-provider.js`.
