proper-base

Baseline Pi behavior for quieter transcripts, automatic session titles, model-preserving /clear, project prompt history, prompt editing, fullscreen navigation, image handling, cancellation, autocomplete, and footer layout.

User-facing features

Sessions and transcript

• Completed tools and errors collapse into separate one-line rows after a run settles. Click one row to expand it, use its collapse control to close it, or use Pi's normal tool-output shortcut, Ctrl+O by default, for all rows. Settlement resets Pi's global tool-output state to collapsed. Thoughts, tool-calling text, direct replies, and agent status updates remain fully visible and in their original order.
• A fresh unnamed session gets a hidden 3 to 7 word title from the first successful assistant response. Existing, resumed, and already-named sessions keep their names.
• /clear starts an empty session but restores the exact provider and model selected in the previous one. No messages, name, or branch state carry over.
• The model you pick in /model and the level you pick in /thinking become Pi's startup defaults, so the next session opens on them. Pi otherwise saves those only when you press Ctrl+S in the picker, and because Pi re-derives the thinking level from the saved default on every model switch, an unsaved level is otherwise lost mid-session at the next /model, Ctrl+P, or /clear. Switching to a model that cannot reach the current level records the level you actually get. Resuming a session does not redefine the model. Set "stickyDefaults": false in ~/.pi/agent/proper-base.json to turn this off.
• Prompt-template expansions remain model-facing, while the transcript shows the slash command you typed, such as /implement-ready epic-1 4.
• CLIProxyAPI empty_stream failures become normal retryable network errors, so Pi applies its existing retry budget and backoff.

Prompt editing and cancellation

Input	Behavior
Alt+Enter	Insert a newline instead of queuing a follow-up. Pi's own Shift+Enter and Ctrl+J stay intact.
Home	Move to the current visible-row start, then the full prompt start.
End	Move to the current logical-line end, then the full prompt end.
Ctrl+C with text	Clear the prompt without arming exit.
Ctrl+C on an empty prompt	Show Press Ctrl+C again to exit; repeat within 500 ms to quit.
Esc before assistant work starts	Restore the submitted prompt and remove that turn from the active branch.
Esc after assistant work starts	Keep Pi's normal abort behavior.

Dismissing an ask_user_question dialog with Esc aborts the run instead of spending another model turn acknowledging the dismissal. Tool or host failures still reach the model so it can ask in plain text.

Project prompt history

proper-base records eligible editor submissions on a best-effort basis, not transformed Pi session messages. History uses an encoded key derived from the current working directory.

• Up and Down recall prompts from previous sessions in the same project. Up recalls only from an empty prompt; with a draft it only moves the cursor, so Home then Up can no longer replace what you typed.
• Ctrl+R starts case-sensitive reverse substring search. Press Ctrl+R again for an older match, Backspace or Shift+Backspace to broaden the query, Enter to submit, Esc to keep the match for editing, or Ctrl+G to restore the original draft.
• Prompt templates and skills remain in their submitted slash form.
• Built-in and extension UI commands such as /model, /new, and /llm-router-config are not recallable.
• Duplicate prompts keep their newest timestamp. The editor receives at most 200 entries.

History lives under ~/.pi/agent/proper-history/. One private JSONL file is created per encoded working-directory key. Unusual paths that produce the same hyphen encoding can share a file. Prompts over 4096 characters are skipped rather than truncated. Startup reads only the newest 512 KiB; stores above 2 MiB compact to the newest 2000 valid entries. A concurrent append during that rare compaction can lose one entry. Delete one file to forget one key, or the directory to forget all proper-base history.

Autocomplete

• The selected autocomplete description appears in a non-capturing bordered panel above the prompt without moving the editor, list, or footer.
• Slash-command completion works after whitespace and on later prompt lines. It replaces only the active slash segment and ignores slashes inside paths and URLs.
• /model results sort by displayed model ID in descending numeric-aware order. Typed terms must all match when strict matches exist.
• /model takes an optional thinking level after the model name, as in /model anthropic/claude-opus-4 high. Once the model name carries a provider slash, the next word completes against Pi's thinking levels; a word naming no level keeps searching models.
• Tab-completing a model name submits nothing. It leaves the name, a trailing space, and an open level menu led by the level already in effect, so you can type a level straight away or press Enter to keep the current one.
• Tab or Enter on a level completion switches immediately: the level is the last argument, so /model gp<Tab>lo<Tab> picks the model and low without a further Enter. Either key switches only when the complete prompt is a single-line /model ... command.

Fullscreen navigation and selection

Enable Pi's native fullscreen mode with /settings or:

{
  "tuiMode": "fullscreen"
}

proper-base keeps the prompt, queued messages, status, widgets, and footer pinned while Pi scrolls the transcript above them.

Input	Behavior in fullscreen mode
Home, End, PageUp, PageDown	Stay assigned to the prompt editor.
Ctrl+Shift+Home or End	Jump the transcript to its top or bottom.
Ctrl+Shift+PageUp or PageDown	Scroll the transcript by one page.
Double-click	Select a complete one-line URL, path, flag, qualified identifier, or quoted value when possible.

Scrolling away from current output adds a ↓ jump to bottom row above the prompt. Clicking it returns to the newest output without disabling scrollbar dragging.

The transcript's top-right corner carries muted ↑ and ↓ arrows that walk the viewport between your own prompts. Clicking ↓ past the last prompt scrolls to the bottom. While you are scrolled up, a dimmer position/total reading sits centred under the arrows and counts the prompts in the session; it disappears once the viewport is following output again.

Pi 0.85.0 moves the prompt cursor to wherever you click in the prompt. If you click the prompt area to focus the terminal or to select text, turn off Prompt mouse clicks in /settings: clicks on the prompt text then leave the cursor alone while drag-to-select keeps working. The same menu holds the Session action rail toggle. Both persist in ~/.pi/agent/proper-base.json as editorMouse and sessionRail.

Clipboard and model image context

Ctrl+V and Ctrl+Shift+V both use Pi's image-or-text clipboard action. Readable clipboard image paths appear as short [image N] markers. Image-capable terminals render compact previews; text-only terminals show marker source paths. Oversized sources are converted to pixel-bounded PNG thumbnails with the package's asynchronous sharp dependency instead of transmitting the full image for a tiny preview. sharp ships prebuilt macOS arm64/x64 and Linux binaries, so no external image command is required. Pi's accent braille loader animates while conversion runs; the marker and path appear only if conversion is unavailable or fails. When terminal focus returns, active Kitty previews are retransmitted so a lost terminal-side scene cannot remain blank behind Pi's upload cache. Left and Right treat each intact [image N] marker as one cursor token. When the cursor lands on it, Pi inverse-highlights the complete marker; Backspace removes the whole highlighted token. On submit, each marker expands back to the original path the agent can read.

Under TERM_PROGRAM=Scribe, proper-base enables Kitty capability before Pi's renderer starts. Other terminals keep Pi's detected capabilities. Images remain in model context for every tool loop in the turn that introduced them. A later user message replaces older image blocks only in the outbound context copy, so saved sessions, exports, resumes, and branches retain the originals.

Skill context

Pi expands /skill:<name> into a user message holding the whole SKILL.md body, then treats it like any other message. Invoking the same skill twice therefore sends two full copies, and compaction summarizes the body away while the model keeps following instructions it can no longer read.

proper-base keeps each invoked skill present exactly once in the outbound context. A repeat invocation of an unchanged body keeps its request and shows the model a one-line already-loaded note instead of a second copy; a body that changed with its arguments is sent in full. After a compaction, the newest body of each dropped skill is restored on the first user turn following the summary, truncated to a character ceiling per skill and in total so the restored text cannot re-trigger the compaction that just ran. Only the outbound copy changes, so saved sessions, exports, resumes, and branches retain the originals.

Footer

The built-in footer keeps path, branch, cumulative input, output, cache, cost, context use, model, and thinking effort visible in two compact rows. Stable colors separate the metrics; context changes color above 70% and 90%. Supported max and router-provided ultra effort levels use a slow rainbow highlight. Custom replacement footers are not changed.

Install

Node 22.19 or newer is required. The package is tested against Pi 0.85.0.

From npm:

pi install npm:proper-base

From a local checkout:

pi install /path/to/proper-pi-extensions/proper-base

Pi supplies the core @earendil-works/pi-coding-agent and @earendil-works/pi-tui peer packages. The package has no runtime dependencies, no build step, and no install-time npm scripts, and it does not modify Pi settings during installation or runtime. npm install only prepares the development checks below.

This package replaces the former local proper-customs identity. Keep only one registration. Existing data under the legacy proper-history path remains compatible.

Compatibility

• Fullscreen behavior uses Pi's native tuiMode: "fullscreen" renderer.
• Questionnaire cancellation activates only when ask_user_question is installed.
• Editor and footer wrappers compose with existing providers when their Pi interfaces are compatible. Private Pi TUI changes or custom renderers may disable individual enhancements; later-loaded replacements still win.
• Ctrl+Shift fullscreen keys require a terminal that reports modifiers distinctly.
• proper-base has no extension-specific runtime config file or feature toggles.
• Slash commands beginning with __proper- are reserved for internal session recovery.

Development

npm install
npm test
npm run typecheck
npm run test:coverage
npm pack --dry-run
npm publish --dry-run

prepack runs tests and strict type checking before a tarball or publish. Tests use Node's built-in runner. There is no build step.

License

MIT