balaur

Self-maintenance: how Balaur edits and ships itself

Balaur is now terminal-first. The live surface is the balaur Pi terminal plus this repo as a local Pi package. There is no core balaur-agent gateway service. The self-maintenance loop is:

edit ~/balaur/**  →  bun test  →  git commit  →  git push  →  /reload in the terminal

No container, no .control bridge, no separate headless agent.

The loop

Ask Balaur in the terminal to make a change; it runs the repo side itself:

cd ~/balaur
# 1. edit files
# 2. test (mandatory before push — main is the push target)
bun test
# 3. commit + push
git add -A && git commit -m "…" && git push
# 4. reseed Pi config if AGENTS/SYSTEM/models changed
bash scripts/seed-pi-config.sh

Then run /reload in the balaur terminal when the active Pi session should pick up changed extensions, skills, theme, prompts, or model config.

Dependency changes (pi/package.json deps) need cd pi && bun install before reload.

How it’s wired

• Terminal command — bin/balaur loads .env, runs scripts/seed-pi-config.sh, then starts Pi from this package’s local dependency.
• Pi package — pi/package.json declares extensions, skills, and themes. settings.json registers ~/balaur/pi as a local package, so self-edits are live after /reload.
• Push auth — seed-pi-config.sh registers an HTTPS credential helper that echoes BALAUR_GITHUB_TOKEN from the env at push time. The token lives only in gitignored .env; it is never written to .git/config. Push target is main.
• Tests — bun test (memory, Pi extension smoke, skill gate). Run it before every push.

Setup once

1. Fine-grained GitHub PAT scoped to the balaur repo, Contents: Read and write.
2. Put it in .env: BALAUR_GITHUB_TOKEN=github_pat_xxx.
3. Run bash scripts/seed-pi-config.sh or just start balaur.

Safety notes

• Pushes go to main. Always bun test before committing so main never goes red; git revert is the undo. Tighten later by pushing to a branch + PR if you want.
• Balaur runs as you on the host in the terminal. Privacy is structural when on the local model; a frontier model is a deliberate manual /model switch.
• Do not resurrect the old gateway/service unless explicitly asked. Future channels belong as Pi extensions attached to a long-lived terminal/tmux session, so there is one live agent session.

Troubleshooting

Symptom	Check / fix
reload did not pick up changes	run bash scripts/seed-pi-config.sh, then /reload; check ~/.pi/agent/settings.json includes ~/balaur/pi
git push auth error	BALAUR_GITHUB_TOKEN unset/mis-scoped in .env; fix, then rerun scripts/seed-pi-config.sh
tests fail	fix before pushing — never deploy red
local model down	curl http://127.0.0.1:8082/health; operator can inspect journalctl -u llama-apu

Related: skill-level self-evolution (proposing new skills with review) — see SELF_EVOLUTION.md.

This site is open source. Improve this page.