pi-aura

English | 简体中文

Built with AI. Every line of code, test, and document here was written by an AI coding agent (Pi driving DeepSeek models) under human direction, review, and release management. The human owns requirements, acceptance, and publishing; the agent writes and verifies.

A polished terminal interface for the Pi coding agent — welcome header, dense footer, framed editor, telemetry, copy buttons, and a tidy transcript.

Highlights

Install

pi install npm:pi-aura

One session: pi -e npm:pi-aura · Local checkout: pi install /path/to/pi-aura

Requires Pi 1.2.0+ and Node.js 22.19.0+. A Nerd Font unlocks the full icon set; unicode and ascii modes need none.

The welcome header

╭─ Pi v1.4.0 ────────────────────────────────────────────────╮
│
│   ██████          Good morning, Sixteen · ⌨ Deepseek-flash
│   ██  ██
│   ████  ██        model   Deepseek-flash    tools   16
│   ██    ██        cwd     Z:\               skills  pdf
│                   branch  main              session local-ui
│
╰────────────────────────────────────────────────────────────╯

Greeting follows the hour; the name comes from PI_HEADER_NAME → git config user.name → OS user. The grid splits available width into two columns and falls back to one on narrow terminals. Set header: false to hand the slot back to Pi.

The footer

• Git — branch, ahead/behind, staged, modified, untracked, stashed, detached HEAD
• Runtime — 50+ detected runtimes with icons
• Context & tokens — usage, totals, cache-hit rate of the latest response
• Cost — USD or CNY, two decimals, display-only conversion
• Live TPS — estimated throughput while streaming, dimmed during tool calls

On narrow terminals it drops runtime and context first, then Git, session name, hostname, and timer; the cwd stays longest.

DeepSeek balance

With provider deepseek, the footer shows the account balance beside the cost: the CNY total_balance from GET https://api.deepseek.com/user/balance. The key is read from auth.json and sent only to that endpoint. Fetched at startup, cached ten minutes, refreshed in the background with a ten-second timeout — … while loading, -- on failure. It lives in the footerSegments.cost group.

Turn telemetry

> TPS 42.5 tok/s | ~ TTFT 1.2s | + 29.7s | ↑ 567 | ↓ 1.2k | ! stall 1x / 4.3s | ¥ 3.60/M

M = one million tokens; the last value is the list price per 1M tokens, not the session total. TPS is provider-reported output tokens over total generation time. Every field toggles in Telemetry.

Copy buttons

Fullscreen mode frames every fenced code block with its language and a [Copy] label, and adds one to each of your messages:

╭─ sh ─────────────── [Copy] ╮
│ pi install npm:pi-aura     │
╰────────────────────────────╯

Copies without fences, preserving indentation and tabs. Streaming replies have no label until they finish. Toggle via General → Copy buttons (copyButtons).

Tool folding (pi-tidy)

Bundled pi-tidy 0.7.3 (MIT, see THIRD_PARTY_NOTICES.md) takes over the transcript: grouped tool folds with failure counts, rounded per-tool frames, side-by-side diffs, live background jobs, right-aligned User frames, and a framed final reply with the model and time. Boxes leave the last column to Pi's scrollbar. Settings live under tidy in settings.json; edit them in /aura → Tidy.

Settings

Run /aura. Tab/←/→ switch tabs, ↑/↓ move, Enter/Space toggle, Esc/q close.

Stored in aura.json in Pi's agent directory (~/.pi/agent, PI_CODING_AGENT_DIR overrides). Tidy and copy-on-select write to settings.json instead.

Configuration

{
  "header": true,
  "settingsLanguage": "zh",
  "currency": "cny",
  "currencyRate": 7.2,
  "cursorStyle": "underline",
  "icons": { "mode": "nerd" }
}

currencyRate is CNY per USD, display-only. bar and underline cursors need terminal shape support. The full footerSegments and telemetry blocks are in the aura.json written by /aura.

Compatibility

Aura frames editors that keep Pi's native layout and cursor, mouse, and padding APIs, including CustomEditor extensions. It decorates the same instance, so ghost text, key handling, completion, and submit callbacks are preserved; editors registered through ctx.ui.setEditorComponent() are framed whether they arrive before or after pi-aura. Editors without native borders, or whose probe throws, stay unchanged.

Development

npm install
npm run typecheck
npm test
pi -e .

133 tests on node --test. CI covers Pi 1.2.0 and latest, Node 22.19.0 and 24, on Linux, Windows, and macOS. Fonts, mouse, and cursor support need a real terminal — check them with pi -e ..

Acknowledgements

• pi-haiku — footer structure, working timer
• pi-claude-code-tui — logo artwork, rounded editor border
• pi-zentui — footer segments, runtime detection, settings UI
• pi-tps — turn timing, stall detection, TPS
• pi-tidy — vendored transcript renderer (MIT)

Logo artwork derives from Pi's official install script. Thanks to the LINUX DO community.

How this was built

pi-aura is an AI-driven development experiment. Features were specified in conversation, implemented by the agent, and checked with tsc, the test suite, and manual terminal review before each commit. The history — including bug hunts, dead-code cleanups, and reverts — is the real working log, not a cleaned-up narrative.

License

MIT