Arnative

Refined aesthetics. Cohesive tools. Built for Pi.

Overview

pi-arnative replaces pi’s default terminal chrome with a unified, cohesive visual aesthetic.

• Warm Themes: Cohesive, contrast-checked OKLCH color palettes generated without drift.
• Tabbed Header: Compact box menu showing Directory, Model, Context, Skills, Extensions, and Shortcuts.
• Rounded Tool Boxes: Status, spinner, and duration for every tool call with expandable outputs.
• Enhanced Footer: 3-row status grid tracking branch, active duration (30s idle freeze), and token speed.
• Transcript Clock: Timestamps for conversation messages with clean bubble backgrounds.
• Usage Dashboard: Real-time token counts and cost tracking across all local sessions via /usage.

Working Spinner Presets

Configurable via /arnative → Animations (saved to arnative-config.json):

• Diamond Glow (default), Diamond Pulse, Circle Pulse, Circle Wave, Shade Wave
• Braille Column, Braille Level, Kanji Count, Suzhou Tally
• Pi (system), Gemini (Google gradient sweep), and Claude (pulsing marks)

Footer Presets

Configurable via /arnative → Footers:

• Arnative (Full) (default 3-row grid)
• Arnative (Minimal) (single collapsible head row; click or ctrl+alt+m to toggle)
• Pi (system) (built-in footer)

Install

pi install npm:@bismawy/pi-arnative

Apply a theme via /settings → Theme → arnative (or variant). Requires a Nerd Font.

To test locally:

npm run dev

Shortcuts

| Key (Linux / Win) | Action | | --- | --- | | 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 | | /usage | Token & cost dashboard (or /arnative → Usage) | | /arnative | Settings menu (Themes, Headers, Footers, Animations, Usage) | | Click tool / ctrl+o | Toggle tool output box | | ← | Back — step back from submenus/dashboard to menu |

To bind app.session.new in ~/.pi/agent/keybindings.json:

{
  "app.session.new": ["ctrl+alt+n", "alt+n"]
}

• Windows / WSL: Windows Terminal aliases Ctrl+Alt to AltGr; use alt+… (or disable altGrAliasing in WT profile).
• macOS: Uses ctrl+option+….
• tmux / Herdr: If Esc has delay, set PI_TUI_ESC_TIMEOUT=100 in your environment.
• Navigation: ← navigates back to parent menus; Esc cancels or closes the active screen.

Architecture

| File | Role | | --- | --- | | extensions/tools.ts | Rounded tool boxes, spinners, and duration | | extensions/section-headers.ts | Tabbed header and resource box (preset: /arnative headers) | | extensions/footer.ts | 3-row status grid footer and boxed editor (preset: /arnative footers) | | extensions/animations.ts | Working spinner presets and /arnative → Animations picker | | lib/spinner.ts | Spinner preset catalog: frames, cadence, and painters | | extensions/arnative.ts | Settings menu with live preview and navigation | | extensions/timestamps.ts | Message timestamps and bubble backgrounds | | extensions/ui-render-tweaks.ts | Contrast tweaks, selection style, and UI polish | | extensions/usage.ts | Token and cost dashboard (/usage) |

Theme definitions are generated via themes/gen-themes.mjs using OKLCH color math (lib/color.ts).

Variants: sun · zinc · violet · emerald · matrix · cyberpunk · synthwave · gruvbox · nord · dracula

npm test        # Run unit tests and self-checks
npm run themes  # Rebuild all theme variants
npm run preview # Live preview the working tree in your own Pi (stamps a pushable commit)

Pre-publish verification and tag validation are enforced via scripts/release-check.mjs.

Local-first push gate: the global pre-push hook rejects any branch push whose commit carries no live-preview stamp, so a fix cannot reach GitHub unseen. npm run preview launches Pi with this working tree and writes .git/arnative-preview for the exact commit that was shown; editing extensions/, lib/, themes/, or package.json afterwards invalidates it and the hook asks for a fresh preview. The preview must run on a clean tree — commit or stash first.

License

Distributed under the MIT license.

Author

Bisma