Balaur

A sovereign local-first personal agent, run through balaur.

Balaur is a Bun/Ink personal agent with a Johnny Decimal Markdown vault, skills, and one continuous life conversation. It uses @earendil-works/pi-ai for model/provider access and @earendil-works/pi-agent-core for the agent loop. It does not use Pi coding-agent, Pi extensions, Pi TUI, or MCP.

Your life is not a product. The record of your life should live in files you own.

Current shape

• CLI: balaur / bun run balaur
• UI: Ink/React terminal interface with Balaur branding
• Agent engine: pi-ai + pi-agent-core
• Vault: Johnny Decimal Markdown under the Balaur data directory
• Conversation: one master conversation, plus compactable sub-conversations
• Skills: Markdown skills, including skills stored as vault entries with kind: skill
• No MCP
• REST API gateway: loopback Bun endpoint for exercising the runtime gateway contract

Quick start

bun install
bun run balaur

Optional local REST API gateway:

bun run api
# POST http://127.0.0.1:8787/api/messages
# GET  http://127.0.0.1:8787/api/events?clientId=local
# POST text "/model download" first if the selected local model is not cached

Useful commands in the chat:

/help             show TUI commands and shortcuts
/clear            clear the visible chat
/model            show current model/provider
/model download   allow local model download for this session
/branch <title>   start a focused sub-conversation
/merge            compact and merge the active sub-conversation into master
/branches         show current branch state
/skill:name       apply a Markdown skill
/exit             quit

Useful TUI shortcuts:

Ctrl+C / Ctrl+D   quit
Ctrl+L            clear visible chat
Ctrl+U            clear input
Ctrl+A / Ctrl+E   move to start/end of input
← / →             move input cursor
Backspace/Delete  edit at cursor

Model selection currently uses:

BALAUR_MODEL=anthropic/claude-sonnet-4-20250514 bun run balaur

API keys are read from standard provider environment variables supported by pi-ai, or BALAUR_<PROVIDER>_API_KEY.

Project layout

src/          CLI entrypoints (`balaur`, reindex) and Ink TUI components
lib/runtime/  Balaur runtime: event bus, gateway bridge, agent wrapper, master/branch conversation, skills
lib/tui/      Pure TUI state helpers
lib/vault.ts  Johnny Decimal Markdown vault + disposable SQLite FTS index
skills/       Built-in Markdown seed skills
assets/        Avatar/source PNG sprite sheets
lib/avatar/    ANSI avatar renderer: sextant + octant only
lib/design/    Shared React/Ink design tokens
lib/gateways/  Legacy transport source; active gateway contract lives in lib/runtime/gateway.ts
docs/adr/      Architecture decisions

Development

bun run typecheck
bun run test
bun run reindex

Bun single-file target:

bun run build:balaur:bun

Migration status

The Pi extension product has been removed from the active package/runtime. Avatar rendering, shared design tokens, and a provider-agnostic runtime gateway contract have been migrated into Pi-free modules. The first active gateway surface is a Bun-native loopback REST API; WhatsApp/Signal-style gateways can attach to the same contract later.

Do not reintroduce Pi coding-agent dependencies. See ADR 0002.

License

AGPL-3.0-or-later. Your private vault and conversations are not part of this repository.

Built in the open, in Brașov.