@bismawy/pi-arnative
Refined aesthetics. Cohesive tools. Built for Pi. Warm themes, rounded tool boxes, tabbed header, compact footer and a /usage dashboard.
Package details
Install @bismawy/pi-arnative from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@bismawy/pi-arnative- Package
@bismawy/pi-arnative- Version
0.16.1- Published
- Nov 21, 2026
- Downloads
- 3,837/mo · 1,203/wk
- Author
- bismawy
- License
- MIT
- Types
- extension, theme
- Size
- 1.2 MB
- Dependencies
- 0 dependencies · 3 peers
Pi manifest JSON
{
"image": "https://raw.githubusercontent.com/bismawy/pi-arnative/main/assets/banner.webp",
"themes": [
"./themes/*.json"
],
"extensions": [
"./extensions/*.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
Arnative
Refined aesthetics. Cohesive tools. Built for Pi.
Overview
pi-arnative replaces Pi's default terminal UI with warm themes, rounded tool boxes, a tabbed header, a status footer, and session tools.
- Themes: 14 contrast-checked OKLCH themes (
arnativeand 13 variants). - Header: Tabbed box showing Directory, Model, Context, Skills, Extensions, and Shortcuts.
- Tool boxes: Rounded borders with status, spinner, duration, and clickable
[show]or[hide]toggles. - Task list:
todotool,/todosrecap screen, and a boxed widget above the editor that hides 30s after all tasks finish. - Footer: 3-row status grid (
Arnative (Full)) or a single collapsible row (Arnative (Minimal)) with git branch, diff stats, active duration, token speed, and optional session cost. - Spinners and timestamps: 18 animated spinner presets with an optional
[g]gradient sweep, plus per-message timestamps and bubble backgrounds. - Usage and budget:
/usagetracks local token counts and spend across sessions, with optional Prometheus export to~/.pi/agent/arnative/usage.prom(setPI_ARNATIVE_EXPORT=0to disable). Budget settings in/arnativeadd UTC day and rolling 30-day spend caps with footer warnings at 80% and 100%, and can block the next turn when enforced. - Providers and model heal:
/providersprobes endpoints and saves OpenAI-, Anthropic-, Gemini-, or Ollama-compatible channels tomodels.jsonandauth.json./model-healfills missing compat flags,/modelstoken limits, and accepted reasoning effort levels. - Context and rendering:
Render cache(Onby default) caches settled transcript components inchatContainer.Auto-compact(Offby default) triggers compaction via Smart tiers or a fixed token budget, with silent in-memory byte trimming for byte-capped proxies.
Install
pi install npm:@bismawy/pi-arnative
Requires a Nerd Font. On a fresh install, arnative is applied automatically if no theme is set. You can switch themes anytime from /arnative or /settings.
For local development:
npm run dev # run pi against this checkout without installing
npm run overlay # copy extensions/, lib/, and themes/ into the installed npm package
Run npm run overlay and then /reload in Pi to test local changes without reinstalling or restarting. Removed modules are pruned from the installed copy, and pi update --extensions restores the published package when a newer version is out. Use npm run overlay -- --dry-run to preview changes, or set PI_CODING_AGENT_DIR to target another agent directory.
Commands and shortcuts
| Command | Purpose |
|---|---|
/arnative |
Open settings (Themes, Headers, Footers, Animations, Render cache, Auto-compact, Model heal, Payload limit, Providers, Usage, Budget) |
/usage |
Open the token and cost dashboard |
/todos |
Open the full task list recap |
/providers |
Manage custom providers |
/model-heal |
Run models.json heal passes now |
In /usage, press R to reset model and provider statistics after confirmation. Session files are left untouched and stay available in /resume. New messages are counted from the reset baseline in ~/.pi/agent/arnative/usage-baseline.json, and U undoes the latest reset while the dashboard is open.
| Key (Linux / Win) | Action |
|---|---|
ctrl+alt+a · alt+a |
Open settings menu (/arnative) |
ctrl+alt+t · alt+t |
Cycle header tabs |
ctrl+alt+r · alt+r |
Quick reload (/reload) |
ctrl+alt+n · alt+n |
New session (/new) |
ctrl+alt+m · alt+m |
Toggle Minimal footer |
ctrl+alt+o · alt+o |
Expand or collapse task list |
ctrl+alt+j · alt+j |
Scroll task list down |
ctrl+alt+k · alt+k |
Scroll task list up |
Click [show] / [hide] · ctrl+o |
Toggle tool output box |
← / Esc |
Go back or close active screen |
Bind app.session.new in ~/.pi/agent/keybindings.json:
{
"app.session.new": ["ctrl+alt+n", "alt+n"]
}
- Windows / WSL: Windows Terminal maps
Ctrl+Altto AltGr. Usealt+...or disablealtGrAliasing. - macOS: Use
ctrl+option+.... - tmux / Herdr: Set
PI_TUI_ESC_TIMEOUT=100ifEscfeels delayed.
Settings from /arnative are saved in ~/.pi/agent/arnative/config.json:
- Headers and footers:
Arnative (Full)(default),Arnative (Minimal)(footer only; click the head text or pressctrl+alt+mto toggle), orPi (system). - Footer cost: Off by default. Press
[c]in the Footers picker to show session cost ($0.42, or~$0.42when estimated) in the metrics row. - Chatbox:
Arnative(default rounded box with 12 prompt icons cycled via[i], coloredprimarywhile typing anddimafter 3s idle) orPi (system). Press[D]to position the working status dialog (Left,Center,Right,Inside,Outside). - Animations: 18 presets (
Arnativedefault,Pi (system), and variants). Press[g]in the picker to toggle the gradient sweep. - Render cache:
Onby default. Reuses rendered lines for settled transcript items inchatContainer. Streaming items, active animations, and custom renderers bypass the cache. - Auto-compact:
Offby default (Pi core compaction handles context).Smartadapts toRender cacheandcontextWindow(triggers at 90% on>= 192kwindows whenRender cacheisOn, or conservative tiers whenOff). Fixed budgets (100kto400k) trigger at an absolute token count, subject to Pi corereserveTokensand provider limits. - Payload limit: Configured in
/arnativeorPI_ARNATIVE_BYTE_WALL_MB(Off,1 MB,4 MB,8 MB,16 MB,32 MB, orCustomfrom 1 to 1024 MB). Forremote/*,remote-magpie/*, and models that return HTTP 413, payloads near the ceiling are trimmed in memory before sending without changing session history. - Model heal:
Full(default: offline compat flags,GET /modelslimits, and reasoning effort probes cached locally),Flags(offline only), orOff. Hand-edited fields are never overwritten. - Task list: Stored per session in
~/.pi/agent/arnative/todos/<session-id>.json(uninstall@juicesharp/rpiv-todofirst to avoid a tool name conflict). Auto-hides 30s after completion (PI_ARNATIVE_TODO_HIDE_MSoverrides the delay;0hides immediately).
| File | Role |
|---|---|
extensions/arnative.ts |
/arnative settings menu and live preview pickers |
extensions/section-headers.ts |
Tabbed header and resource box |
extensions/footer.ts |
3-row status grid, Minimal footer, and boxed editor |
extensions/tools.ts |
Rounded tool boxes, spinners, duration, and [show] / [hide] toggles |
extensions/todos.ts |
todo tool, boxed widget above editor, and /todos screen |
extensions/animations.ts |
Spinner preset picker and live preview |
extensions/autocompact.ts |
Smart and fixed-budget context compaction plus silent byte-wall shedding |
extensions/render-cache.ts |
Per-child and container transcript render cache for chatContainer |
extensions/budget.ts |
UTC day and rolling 30-day spend caps and footer warnings |
extensions/usage-export.ts |
Prometheus textfile metric export (usage.prom) |
extensions/model-heal.ts |
Automatic models.json heal triggers and /model-heal |
extensions/timestamps.ts |
Message timestamps and bubble backgrounds |
extensions/ui-render-tweaks.ts |
Contrast tweaks, selection styling, and UI polish |
extensions/usage.ts |
Token and cost dashboard (/usage) |
lib/todos.ts |
Task state, window layout, box rows, and session store |
lib/spinner.ts |
Spinner preset catalog, frames, and gradient painters |
lib/provider.ts |
Custom provider probe, model picker, and config writer |
lib/model-heal.ts |
Compat flags, /models limit sync, and reasoning effort probe |
lib/list-picker.ts |
Shared live-preview and multi-select picker component |
Themes (themes/gen-themes.mjs + lib/color.ts): arnative · arnative-blossom · arnative-crimson · arnative-cyberpunk · arnative-dracula · arnative-earthy · arnative-garden · arnative-gruvbox · arnative-lemonade · arnative-magical · arnative-matrix · arnative-neutral · arnative-nord · arnative-zinc
npm test # Run self-checks and unit tests
npm run themes # Regenerate theme JSON files
npm run preview # Live preview in Pi and stamp .git/arnative-preview
git config core.hooksPath .githooks # Enable pre-push preview verification hook
License
Distributed under the MIT license.
