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 color palettes generated without drift.
• Tabbed Header: Greeting, version line, and a compact box menu over Directory, Model, Context, Skills, Extensions, and Shortcut.

  The Context/Skills/Extensions counts read pi's startup listing, which "quietStartup": true (and "header") hides. Under those settings the counts show — rather than a misleading 0; set "quietStartup": false to see the real numbers.

• Rounded Tool Boxes: Clear status, spinner, and duration for every tool call. Built-in codemode is boxed and collapsed to two rows (title + first script line) like bash/grep/read; nested calls and output sit behind [ctrl+o to expand] (shown whenever the collapsed summary hides more, including edit diffs); a failed run always shows its full output. The chrome_devtools_* tools box too, replacing their bare "Chrome DevTools: …" lines.
• Enhanced Footer: fixed 3-row grid — directory/git line, then extension status paired with token metrics.

  The branch is read straight from .git/HEAD, so it shows up without a git install. Tag, dirty count, and ahead/behind need the git binary — when it is missing (or the repo is owned by another user, which git refuses to touch) that half is left out rather than shown wrong. Run git config --global --add safe.directory <repo> (a local, non-synced setting) to make git cooperate with such a repo.

• Transcript Clock: Timestamps for messages with clean bubble backgrounds.
• Usage Dashboard: /usage command to track tokens and session costs.

Install

pi install npm:@bismawy/pi-arnative

Select a theme via /settings → Theme → arnative (or any arnative-* variant).

To test locally without installing:

pi --extension ./extensions/footer.ts

Prerequisite: Requires a Nerd Font (e.g. JetBrains Mono Nerd Font) for icons and rounded box borders.

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) — requires keybinding below
/usage	Show session usage & token metrics
/arnative	Settings menu — Themes, Headers, Footers
Click tab	Open selected header tab
Click tool / ctrl+e	Toggle tool output box

Notes:

• Windows / WSL: Windows Terminal aliases Ctrl+Alt to AltGr; use alt+… (or set "altGrAliasing": false in WT profile).
• macOS: uses ctrl+option+… (plain Option composes special characters).
• Herdr / tmux glitch: if shortcuts feel delayed or type stray letters, set PI_TUI_ESC_TIMEOUT=100 in your shell profile.

Keybindings

Add to ~/.pi/agent/keybindings.json to bind app.session.new:

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

Architecture

Extensions

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/arnative.ts	/arnative settings menu — live-preview theme/header/footer pickers
extensions/timestamps.ts	Message clock and bubble background fixes
extensions/ui-render-tweaks.ts	Contrast tweaks, selection style, and UI polish
extensions/usage.ts	/usage token dashboard

Themes

• themes/gen-themes.mjs is the single source of truth: it writes every themes/*.json, including the base arnative.json.
• Each theme is a few parameters (accent hue, chroma, canvas lightness, neutral tint) plus optional hue overrides for the strong palettes; all colors are derived as OKLCH from a shared ramp, so lightness/saturation stay consistent and no two vars collapse to the same value.
• lib/color.ts holds the OKLCH↔sRGB math and WCAG contrast used by both the generator and the self-check.

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

Development

npm test        # Run self-checks & theme generator check
npm run themes  # Rebuild all theme variants

Releasing: scripts/release-check.mjs is a read-only preflight (never writes, tags, pushes or publishes) with one stage per step of the release:

Stage	Run before	Checks
pre-tag	git tag	clean tree on main, in sync, no open PRs, CHANGELOG.md entry, tag free, version unpublished
pre-publish	npm publish	the above, plus the tag exists and is pushed, and points at HEAD
post-publish	done	the above, plus the version is live on the registry, latest points at it and its tarball URL answers

pre-publish runs automatically through npm's prepublishOnly (after npm test), so a red build or a missing/unpushed tag aborts the publish (npm error code 1) instead of shipping a version whose tag was forgotten. The open-PR check uses gh when present and falls back to the public GitHub API otherwise. npm run release:check is the pre-tag shorthand. Exit codes: 0 pass, 1 a check failed, 2 bad usage.

License

Distributed under the MIT license.

Author

Bisma