Status: Current release:
0.1.1. Pi-TUIX is available on npm.
Pi-TUIX is an open-source terminal UI extension for the Pi Coding Agent. It adds a clearer, denser interface for long coding sessions while Pi continues to own model requests, built-in tools, sessions, permissions, and provider integrations.
When a coding session is long, the hard part is often knowing what is happening, what changed, and whether you need to intervene. Pi-TUIX improves that information hierarchy without moving your work to a second agent runtime.
- See the active model, workspace, and context signal in the shell.
- Keep working and streaming feedback visible without transcript noise.
- Review or resume saved sessions without replaying their tools.
- Paste supported local images into the editor while Pi continues to own delivery.
- Switch back to Pi's default interface in the same session.
- Adopt it as a removable package; Pi remains the system of record.
Requirements: Node.js >=22.19.0 and Pi Coding Agent >=0.84.0. Install Pi-TUIX for your user with one command:
pi install npm:pi-tuix --approvePi will download the package and load it automatically for future sessions. Restart Pi after installation. Check the active package with:
pi listTo restore Pi's native interface in a session, use /pituix-default. Use /pituix to enable Pi-TUIX again.
To test a local checkout instead of the npm release:
git clone https://github.com/HuangYuChuh/pi-tuix.git
cd pi-tuix
npm install
npm run check
pi install /absolute/path/to/pi-tuix --approve
pi listPi follows the local working tree after restart. Use pi install -l /absolute/path/to/pi-tuix --approve for a project-local installation, or pi -e ./extensions/index.ts for a one-off preview that is not saved.
See Using the development version for local installation and Releasing Pi-TUIX for development, prerelease, and stable channel rules.
The development shell follows observed Claude Code 2.1.263 terminal layout: compact startup information, horizontal prompt rules, contextual shortcut help, and a one-line footer. /pituix-status reveals detailed Git/runtime/context/cost statistics. This is a partial visual adaptation; see the reference observations and remaining gaps.
The editor extends Pi's public CustomEditor, preserving submission, history, autocomplete, paste handling, and registered application shortcuts. Press ? on an empty draft for help. /pituix-default restores native components and the previous theme in the active session. It also saves the disabled preference; /pituix saves the enabled preference. The settings switch uses this same state, including after restart or reload. The enabled state applies when the settings page closes, and disabled runs do not add Pi-TUIX completion records or telemetry notifications. Icon selection also applies to tools, working feedback, completion history and session previews.
The effective thinking level appears above the prompt with Pi's configured shortcut. /pituix-settings opens searchable preference tabs: type to filter, press Enter to select a result, then Enter or Space to change it. Tab switches categories; Escape clears the query, leaves search, then closes the page.
Each tool row keeps the action, target, state, and attention signal visible. Read defaults to a line-count result branch; Bash shows output, Edit uses an Update heading with a numbered diff, and Write previews numbered content. Long previews show the first and last two detail lines. Collapsed mode keeps the summary; expanded mode reveals the full output or diff, including Read contents. Errors retain their details. All views use ANSI-aware width constraints.
Adjacent successful Read/Bash calls combine into a count summary, deduplicating file paths while counting each shell call. Expand tools to reveal every call. Successful Read images also use file counts, with byte summaries on expansion. Errors, cancellation, Bash images, and truncated results remain separate; assistant text and other tools separate groups. Grouping is reconstructed from Pi's public session branch when resuming.
In the reference dark theme, Edit diffs use numbered +/- gutters, full-row backgrounds and stronger changed-word backgrounds. Added/context lines use Pi's syntax highlighter. Other themes retain Pi's diff styling; 256-color and no-color terminals have explicit fallbacks.
The working line shows elapsed time and reported output tokens when available. After Pi settles, a completion line shows duration and clock time, or an interruption prompt after cancellation. Pi saves one display-only entry per settled run, so these rows survive later requests and session resume/reload. They stay outside model context, hide with /pituix-default, and reappear with /pituix. Removing the package leaves ordinary Pi sessions usable; older runs without timing records are not backfilled.
/pituix-resume searches saved Pi sessions. Type to filter, press Enter to select a result, then Enter again to resume. Space opens a read-only conversation preview with individual tool results, diffs, recorded model/time and completion rows. Use arrows, PgUp/PgDn, Home/End or the wheel to scroll and Ctrl+O to expand details. Esc returns to the list; Ctrl+A switches project scope. Pi performs the actual session switch. The preview uses Pi's active-branch/compaction projection; it never executes recorded tools or rewrites session files. Native /resume and /tree remain available.
Session rows show file size and the Git branch recorded when a run ended. Preview footers show message count and that same recorded branch. Ctrl+B filters the list to the current Git branch; older sessions without a recorded branch are excluded. Metadata loads asynchronously near the visible selection, or across the selected project scope while branch filtering, with at most two concurrent reads. Closing stops queued work.
Ctrl+R (or Pi's configured session rename binding) edits the selected session's name. Enter saves through Pi's public session API; Esc cancels the draft. Saving a name refreshes the list without resuming the session. The active session uses Pi's live setter, and other sessions use Pi's native name entries. Confirmed renaming of legacy files may invoke Pi's normal format migration; search, filtering and previews remain read-only.
The main conversation uses reference-style user and assistant rows in both regular and fullscreen terminal modes, while retaining Pi's editor, streaming output, tools, notifications, widgets and queue. Assistant Markdown keeps Pi's public parser and syntax highlighting, with measured presentation adjustments: code fences are hidden, fenced code aligns with the normal response body, table headings are centered within Pi's calculated columns, and quote bodies are italicized beside Pi's quote rail. The same treatment is shared by live messages, /pituix-transcript, and resume previews. Fullscreen scrolling, prompt navigation, search and mouse selection use Pi's native viewport over the same styled document; closing search retains the matched location. Regular mode uses terminal scrollback. Pi's settings can switch between modes during a session. /pituix-default restores the native interface in that session.
/pituix-transcript also opens a read-only snapshot of the current conversation and recorded tool results. Use Page Up/Down or Home/End to scroll, the configured tool-expansion key to reveal details and thinking, and Esc to return to the same editor. It does not rerun tools or change session data. Other extensions' tools use a generic public Pi view.
The main conversation and both readers show user image attachments such as [Image #1] next to their prompts, including image-only messages. Only user attachments consume numbers. Saved positional labels retain their numbers, including gaps after deleting a draft image; other attachments are numbered in displayed branch order. Successful Read images show a file/byte summary, and other tool or custom images use unnumbered [Image] links. Click an attachment branch in fullscreen mode to open it; regular mode uses the terminal's hyperlink gesture. Supported PNG/JPEG/GIF/WebP data is prepared asynchronously in private temporary files and removed on normal runtime shutdown. Missing or unsupported data keeps an unavailable label. Main-view search and prompt navigation include the attachment rows.
Pasting a PNG/JPEG/GIF/WebP path, or using Pi's native clipboard-image action, inserts an [Image #N] chip at the cursor. A list of absolute, home or file-URL paths separated by whitespace inserts multiple chips in order; escape spaces within list paths. A list whose paths are individually quoted stays unchanged. When a list contains at least one valid image, missing paths are ignored and existing non-image paths remain text; a paste containing ordinary prose stays unchanged. Arrow keys and deletion treat each chip as one item. Pi's undo restores a deleted image or removes an entire batch paste. Submission and follow-up queues use Pi's public input transformation to deliver captured bytes with positional labels. Draft links open those captured images; external editing exposes restorable labels for current attachments. Repeated references to one current attachment share its bytes; removing every reference removes that attachment. Separate image pastes remain separate, and disabling the extension leaves readable file paths in the draft. Typed paths remain text. Historical and manually typed [Image #N] labels also support whole-label layout, movement, deletion and undo, while remaining text without image bytes. Literal-label deletion stays native when the draft contains collapsed paste data. Queue take-back and interruption restore observed image drafts in Pi's steering/follow-up order, while same-number literal labels remain text. If the returned queue text cannot be verified, Pi-TUIX keeps it and asks you to check and reattach missing images.
A fresh editor continues numbering after user labels on the selected saved branch. A successful image paste also checks labels in the current visible draft; discarded text and live text-only messages do not consume numbers. Delivered chips save a small display-only number annotation through Pi, so unrelated literal labels cannot renumber their attachments after sending or resuming. The annotation contains no source paths or image bytes and stays outside model context. Long text pastes still use Pi's native labels and separate counter.
Closing a custom dialog that restores the unchanged draft on the same editor preserves collapsed text, attachments, cursor position and native undo. This does not transfer collapsed paste data to a replacement editor or a changed draft.
Press ? on an empty draft to see Pi's configured image-paste shortcut (normally Control+V on macOS). An input method's fullwidth question mark also opens help on an empty draft. These two workflows attach local images:
- Copy image contents: open the image in Preview, select it with Command+A, then Command+C. Focus the Pi input and press Control+V, or your configured image-paste shortcut.
- Copy a file path: select a local PNG/JPEG/GIF/WebP file in Finder and press Option+Command+C to copy its full path. Focus Pi and use the terminal's normal paste command, such as Command+V in Orca. Paste the path separately from your question.
Check that an [Image #N] chip appears, then add your question and send. Command+V is handled by the terminal; copying a filename or file reference does not always provide image pixels or a usable path. Typing a path or [Image #N] by hand does not attach an image.
| Symptom | What to check |
|---|---|
| Neither paste method creates a chip | Check that the image exists on the Mac running Pi. Remote clipboard software can provide a zero-byte placeholder instead of the actual file; complete the file transfer first. Finder's Edit > Show Clipboard can identify a file URL. A file URL alone does not establish that image bytes are available. |
| A chip appears, but the model cannot see the image | Check that the provider actually supports image input and that the selected custom model declares "input": ["text", "image"] in Pi's models.json. Open native /model to reload an edited catalogue and reselect the model. Changing this declaration cannot give a text-only provider vision support. |
| Large photos take a long time to send | Pi-TUIX captures the original file bytes. Resize a local copy before pasting if the original is large. |
For comparison, /pituix-default restores Pi's native input; /pituix brings this interface back. Clipboard access, remote file transfer and model capabilities remain outside Pi-TUIX.
These commands are reversible:
| Command | Purpose |
|---|---|
/pituix |
Enable or restore the Pi-TUIX shell and reference theme |
/pituix-default |
Restore Pi's default TUI components |
/pituix-compact |
Collapse reference-style tools to summary rows |
/pituix-three-layer |
Show reference-style tool previews with expansion |
/pituix-mode <collapsed|preview|expanded> |
Set the tool detail display mode; preview is the default |
/pituix-about |
Show the package and compatible Pi version |
/pituix-status |
Toggle compact hints and detailed session statistics |
/pituix-model |
Choose a Pi model and thinking level in the numbered picker |
/pituix-resume |
Search, filter, rename, preview and resume saved Pi sessions |
/pituix-session |
Navigate entries in the current Pi session tree |
/pituix-transcript |
Read a scrollable snapshot with message and tool detail |
/pituix-settings |
Open shell, footer, icon, and telemetry settings |
/pituix-steer <message> |
Interrupt the current run with an immediate correction |
/pituix-followup <message> |
Queue work to start after the current run |
/pituix-queue |
Show whether Pi has queued follow-up messages |
/pituix-plan [show|hide|clear] |
Control the detected read-only plan panel |
The bundled pi-tuix-dark theme is applied with the shell and remains available from Pi's /settings screen. The project includes adapted MIT-licensed code from OldSuns/pi-open-tui; see THIRD_PARTY_NOTICES.md.
If colors change after native /new, /resume, or /reload on Pi 0.84.4, Pi-TUIX watches the public ctx.ui.theme value while its shell is active and rebinds its custom components when the host theme changes. This compatibility fallback does not patch Pi's private theme controller and stops when the shell is disabled. Recovery applies a temporary theme without changing Pi's saved theme setting. /pituix-default restores the theme that recovery replaced, unless you select another theme afterward.
Pi-TUIX is a presentation layer around Pi's supported extension hooks:
Pi Coding Agent (runtime, providers, tools, sessions, permissions)
|
public ExtensionAPI
|
Pi-TUIX shell
(header, footer, indicators, themes)
Components render state. Lifecycle handlers translate Pi events into small UI updates; they do not call providers or execute shell commands as a rendering side effect. Tool renderers delegate execution to Pi unchanged and replace only the call/result presentation.
The stream line distinguishes thinking, response text, and tool execution by turn. Context pressure is labelled HIGH at 80% and CRITICAL at 95%. When an assistant response contains a Plan: heading followed by numbered or checkbox steps, Pi-TUIX shows a width-safe read-only plan panel above the editor. The panel reflects checked items and [DONE:n] markers without changing prompts, tools, or execution.
- Shell (current): header, footer, theme, working state, and reversible editor chrome. Pi retains its native session and project title in terminal tabs.
- Tool surface (current): three-layer Read/Bash/Edit/Write rows with collapsed, preview, and expanded modes; explicit queued/running/success/error/cancelled states; and diff summaries.
- Stream surface (current): thinking/responding/tool activity, turn progress, thinking level, context pressure, and stable repainting.
- Control surface (in progress): steer/follow-up queue commands and read-only plan review are available; approval adapters and keyboard conventions remain planned.
- Session surface: context inspection, resume references, subagent state, and session surfaces where Pi exposes reliable public events.
The scope and acceptance criteria are documented in docs/product-context.md. The product boundary is in docs/positioning.md, and the runtime design is in docs/architecture.md.
- Host: Pi Coding Agent
>=0.84.0. - UI runtime:
@earendil-works/pi-tui>=0.84.0as a peer dependency. - Ownership: Pi owns model calls, tool execution, sessions, permissions, credentials, and persistence.
- Public APIs: implementation targets Pi's documented extension contracts; private Pi modules are not patched or vendored.
- Reversibility: disabling or removing Pi-TUIX does not require migrating Pi sessions or project files.
- Provenance: no Claude Code source, private protocol, branding, or proprietary asset is included.
- Product context - user problem, MVP workflow, and non-goals
- Positioning - ownership boundaries and design principles
- Architecture - event-to-view rules and compatibility strategy
- Development version - persistent local installation and channel switching
- Release process - version, npm channel, tag, and publication gates
- Documentation policy - what belongs in public documentation
- Contributing - local setup and pull-request expectations
- Security policy - vulnerability reporting
Focused issues and pull requests are welcome. Before changing a renderer or lifecycle hook, run:
npm run check
npm run test
npm run pack:checkUI changes should be checked at narrow and normal terminal widths, including idle, running, success, error, and cancellation states. Tool renderer changes must demonstrate that Pi's execution, cancellation, errors, and permissions remain unchanged. See CONTRIBUTING.md for the full checklist.
Pi-TUIX is released under the MIT License.