balaur

Balaur

Your personal wise companion that grows with you.

· AGPL-3.0 · built on Bun

A self-hosted AI companion that runs on your own box, remembers what matters in a Markdown vault, and grows a new skill — a new head — for every procedure you teach it. Local model by default; your data stays yours.

→ balaur.org · Design

Current architecture is deliberately small:

• balaur — branded Pi terminal session.
• pi/ — local Pi package: extensions, native skills, theme, model config.
• llama-apu — local model service on 127.0.0.1:8082.
• $VAULT_PATH — private Markdown vault outside the repo.

There is intentionally no core HTTP gateway / always-on balaur-agent service now. Future Signal/web/HTTP bridges should be Pi extensions attached to a long-lived terminal/tmux session, so there is one live agent session and no split-brain model state.

Quick start

git clone https://github.com/alexradunet/balaur.git ~/balaur
cd ~/balaur
./install.sh
balaur

Health check:

make doctor

What it gives you

• Local/private model default (llama-apu, Qwen3.6 by default).
• Manual opt-in frontier models via /login + /model.
• Markdown memory tools backed by FTS5.
• Journal/diet/sport/vault tools.
• Pi-native skills under pi/skills/.
• A compact Balaur terminal UI/theme.
• Self-maintenance through plain git: edit → bun test → commit → push → /reload.

Repo map

bin/balaur                 # terminal launcher
pi/                        # Pi package: extensions, skills, themes, model config
pi/extensions/             # memory, vault, Balaur terminal UI
pi/skills/                 # Pi-native Markdown skills
pi/themes/                 # Balaur theme
docs/                      # install, troubleshooting, maintenance docs
scripts/seed-pi-config.sh  # registers the local Pi package in ~/.pi/agent
scripts/setup-local-llm.sh # installs/configures llama-apu
scripts/doctor.sh          # make doctor

Commands

make doctor      # tooling/deps/tests/local-model/Pi-config health check
make test        # bun test
make smoke       # Pi SDK smoke check
make index       # rebuild vault/memory FTS index
make cli         # open the terminal via bin/balaur

Inside the terminal:

/reload          # reload extensions/skills/theme/prompts
/model           # switch model
/login           # optional frontier login
/skill:doctor    # run the doctor playbook

Docs

• Install
• Troubleshooting
• Self-maintenance
• Self-evolution
• Design

Privacy stance

Personal data stays in the vault by default. The local model is the default. Frontier models are manual and opt-in; do not move personal memory to them automatically.

This site is open source. Improve this page.