balaur

Balaur Pi terminal design

The Pi terminal is Balaur’s owned daily surface. It should feel like an old-school fantasy RPG command interface, but still be compact, truthful, and useful.

Goals

• Make Pi feel like Balaur, not a generic coding agent.
• Keep private/local state legible.
• Add RPG flavor through structure: nameplates, ASCII frames, terse wise copy.
• Keep canonical per-avatar 3×3, 9-frame, 64×64 PNG sprite sheets; render Kitty PNG avatars when supported, and ASCII nameplates/badges as the unsupported-terminal fallback.
• Avoid taking over the whole screen.

Current implemented pieces

• Compact ASCII pixel header.
• Fixed-width RPG message gutters:
  • avatar default: portrait only, no badge/name.
  • badge: [ <BALAUR_USER_NAME> ] | and [ Balaur ] |.
  • both: portrait first, badge underneath.
  • backend auto: Kitty PNG image when supported; badge fallback otherwise.
  • BALAUR_AVATAR_RECENT_LIMIT=10: cap rich image avatars to recent panels; older history uses badges for performance.
• Working/thinking state is shown as a Balaur-owned transient chat-like assistant portrait widget, not as a sentence or Pi’s default loader row; in both mode it shows the thinking badge under the portrait.
• Truthful footer:
  • local model -> local/private
  • frontier model -> frontier/opt-in
  • dirty git state -> git:branch*
  • context usage -> compact ASCII meter on wider terminals
• Thinking blocks hidden by default with no placeholder line; the animated avatar is enough.
• Quiet ASCII RPG panels around user, assistant, thinking, tool-call turns, and the input editor.
• Tool output collapsed by default and wrapped in the same dialog-panel style.
• Per-tool generated pixel icons for read/edit/write/bash/search/memory/doctor/skill-evolution states; in both mode the icon gets a compact [ tool ] badge under it.

RPG nameplate rules

Nameplates use a fixed-width gutter across all roles, so messages align vertically.

Good:

[ cico   ] | ask
[ Balaur ] | answer

Rules:

• User name comes from BALAUR_USER_NAME in .env, falling back to $USER, then You.
• The gutter width is computed from the longer visible label.
• Use muted divider color; keep role color only inside the nameplate.
• Keep visible badges simple and centered: [ Name ], no @/B/?/T prefix.
• Do not let user-message background bleed into the left gutter.
• Stay ASCII-safe in fallback mode. Avoid emoji and box-drawing in the fallback terminal UI.
• Modes: BALAUR_AVATAR_MODE=badge|avatar|both.
• Backend: BALAUR_AVATAR_BACKEND=auto|image|ansi.
• Performance cap: BALAUR_AVATAR_RECENT_LIMIT=<n|all>; default 10, 0 means active-only rich avatars.
• Runtime toggle: /balaur-avatar [badge|avatar|both] [auto|image|ansi].
• Role portraits and tool icons use canonical per-avatar 3×3, 9-frame, 64×64 PNG sprite sheets. The chat gutter may render them as Kitty PNG; badges remain the unsupported-terminal fallback.

Sprite rules

Mode/backend source of truth: ../pi/lib/ui/sprites.ts. Canonical role sprite source of truth: ../pi/lib/ui/pixel-avatar.ts.

Current internal sprite catalog:

@  user/player
B  Balaur idle
?  Balaur thinking
T  tool work
M  memory/life tracking
+  doctor/health check
*  self-evolution/new capability

Only @ and B are currently rendered in message nameplates. The other states are reserved so the interface can evolve without inventing new visual language each time.

Working state

The working state should be portable and quiet.

Rules:

• Do not print a working sentence like Hmm... I will think about that..
• Do not show a plain status-line spinner for normal thinking.
• Render thinking as the same RPG portrait-panel format used by assistant turns; in both mode, include a simple [ Balaur ] badge under the thinking portrait.
• Own thinking through an extension widget above the editor; hide Pi’s built-in Loader/Text working row during normal agent streaming.
• Replace the transient thinking widget once answer text begins streaming.
• Use the same PNG sprite-sheet renderer as message panels in Kitty-capable terminals; keep stable image IDs during animation to reduce churn.
• Keep the built-in Loader/Text fallback ANSI-only because that path cannot safely repaint animated image escapes.
• Keep one blank separator line between user/assistant turns; avoid stacking bottom and top padding into two-line gaps.

Message borders

Messages use a quiet ASCII RPG dialog panel: a small avatar/nameplate box on the left, message body on the right, connected by a shared border.

Short message:

+----------+----------------+
|          | answer         |
| avatar   |                |
| avatar   |                |
|          |                |
+----------+----------------+

Long message:

+----------+----------------+
|          | answer         |
| avatar   | more           |
| avatar   | more           |
|          | more           |
+----------+ more           |
           | more           |
           +----------------+

Rules:

• Border color stays smoke/muted.
• Use ASCII +, -, | only; no box-drawing in the fallback terminal UI.
• Avatar/nameplate gets its own fixed-size box with one column/row of inner padding.
• Full chat-turn panels keep one outer column of left/right padding, matching the transient thinking panel.
• The message body connects to the avatar box through the shared right edge.
• Text body height is at least the avatar box height; if text is longer, only the message body continues downward.
• While hidden thinking is the only content, show only the transient thinking panel; do not render a persistent empty assistant message body.
• Keep exactly one visual blank separator between turns. Do not add extra bottom padding inside the panels.

Tool-call panels

Tool execution uses the same panel language as chat turns:

 +----------+----------------+
 |          | read file      |
 | hammer   |                |
 | hammer   | result/preview |
 |          |                |
 +----------+----------------+

Rules:

• Do not fall back to Pi’s default unframed tool UI in normal chat.
• Left cell shows a compact generated pixel tool avatar while the tool is pending/running. Common tools get distinct icons: scroll (read), needle/loom shuttle (edit), quill (write), anvil (bash), lens/folder (grep/find/ls), Keeper (memory/life tracking), Warden (doctor/health), New Head (skill_write/evolution), and Seer (open-websearch/web retrieval). Unknown tools fall back to the maker’s hammer. In both mode, tools show a truncated [ tool ] badge under the icon. Tool avatars animate only while actively running; pending/ok/error panels are static.
• Tool avatar foreground/background carries state:
  • gold/umber = pending
  • bright parchment/steel = running
  • teal = success
  • ember/red = error
• Keep the icon hook small so later tools can get distinct animated/static avatars without changing panel layout.
• Keep built-in tool render content on the right so diffs, previews, and errors remain useful.
• Use the same outer one-column padding and smoke ASCII border as chat/working panels.

Input editor

The text input should use the same restrained ASCII panel language as chat turns, including the user’s avatar/nameplate on the left so it visually becomes the next user message when submitted:

 +----------+-- input -----------+
 |          | > draft message    |
 | avatar   |                    |
 | avatar   |                    |
 |          |                    |
 +----------+--------------------+

Rules:

• One-column outer padding, matching chat and thinking panels.
• Left cell follows current avatar mode: badge, avatar, or both.
• Muted indigo ASCII border, so the draft panel reads as user-side input while staying in the same family as chat panels.
• Gold input label; teal > prompt.
• Animate the user avatar subtly while text changes in the editor; stop when empty.
• Preserve Pi editor behavior: history, autocomplete, paste handling, submit shortcuts, cursor.
• Autocomplete content may render inside the input panel; do not introduce a second visual language.

Header

Header should be compact, width-aware, and ASCII pixel-framed. Target shape:

+-- B A L A U R ----------------+
| local-first | private | yours | FOSS |
+--------------------------------+

The header may truncate to terminal width, but must not exceed three lines. On wide terminals it may use the third line for the Basm motto: woven, not rendered.

Footer

Footer should be one line:

Balaur                         local/private | qwen/... | git:main* | 12 tools | ctx [===---] 42%

Rules:

• Never claim local/private for frontier models.
• Put identity left, runtime truth right.
• Keep it dim except the Balaur mark, the local/frontier trust badge, dirty git marker, and high context warnings.

Color rules

Use Basm palette:

• Balaur/name/accent: gold.
• User/name: indigo; avoid making the whole left gutter green.
• Dividers and empty gutter: smoke/muted.
• Thinking avatar marker: gold / ember / teal, kept inside the compact portrait.
• Generated ANSI pixel blocks are allowed for image fallback; emoji remain out of the default TUI because terminal width varies.

Avatar layers

See avatars.md.

• ASCII nameplates are the safest transport format.
• avatar/both use canonical 64×64 PNG sprite sheets: one 3×3, 9-frame sheet per avatar/tool.
• BALAUR_AVATAR_BACKEND=auto uses Kitty PNG images in Kitty-compatible terminals and badges elsewhere.
• iTerm2 image support exists in Pi, but Balaur’s inline chat gutter currently uses Kitty image semantics only; iTerm2 falls back to badges.

Implementation notes

Pi currently exposes custom renderers only for custom messages, not built-in user/assistant role messages. Balaur decorates Pi’s exported UserMessageComponent and AssistantMessageComponent in ../pi/lib/ui/avatars.ts. Keep this patch small, idempotent, and easy to remove if Pi adds official role-rendering hooks.

This site is open source. Improve this page.