An opinionated environment for Pi. Multiple AI agents in tmux, coordinated automatically.
- Multi-agent orchestration — spawn specialized agents (test runner, code reviewer, scout) that work simultaneously in tmux windows
- Mesh coordination — agents reserve files, send messages, and stay out of each other's way
- Background automation — a daemon summarizes sessions, generates builder's logs, fills handoffs, and backs up your workspace on a schedule
git clone https://github.com/oddship/bosun.git
cd bosun
just onboard # install deps, create config
# edit config.toml with your API keys
just start # sandboxed tmux session# In the bosun repo (once, registers it for linking)
cd /path/to/bosun && bun link
# In your project
mkdir my-project && cd my-project
bun init
bun link bosun
npx bosun onboard # scaffolds config, justfile, directories
# edit config.toml with your API keys
just startjust lifecycle recipes now call the Bosun CLI under the hood (bosun start|run|attach|stop|init|doctor).
See Downstream Projects for the full guide.
Then:
You: Explore this codebase and add tests for the auth module
Bosun spawns scout → plans the work → delegates to lite → runs verify
See the full Quickstart.
┌─────────────────────────────────────────────────────┐
│ tmux session │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ │
│ │ bosun │ │ lite │ │ verify │ │ scout │ │
│ │(orchestr)│ │(fast) │ │(tests) │ │(recon) │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬─────┘ │
│ └────────────┴──────────┴────────────┘ │
│ pi-mesh │
├─────────────────────────────────────────────────────┤
│ pi-daemon (background automation) │
├─────────────────────────────────────────────────────┤
│ sandboxing (bwrap + tool-level) │
└─────────────────────────────────────────────────────┘
- Quickstart — Get running in 5 minutes
- Walkthrough — Guided tour of a session
- Agents — Agent tiers, spawning, mesh coordination
- Workflows — Daemon and scheduled automation
- Daily Use — Patterns and commands
- Architecture — Package design and data flow
- Downstream Projects — Build your own environment on bosun
- Packages — Package reference
Independent Pi packages, each usable standalone via pi install npm:<name>:
| Package | Description |
|---|---|
| pi-bosun | Framework identity — default agents, slots, skills |
| pi-agents | Agent discovery, model tiers, spawn_agent |
| pi-auto-resume | Auto-resume after compaction + opt-in early compaction thresholds |
| pi-mesh | Multi-agent coordination — reservations, messaging |
| pi-tmux | Terminal tools — split panes, send keys, capture |
| pi-daemon | Background workflows — scheduling, queue, retry |
| pi-sandbox | Tool-level access control |
| pi-memory | Curated markdown memory retrieval backed by qmd v2 |
| pi-chronicles | Builder's log generation |
| pi-session-tools | Session summarization and handoffs |
| pi-q | Task, project, and roadmap management |
| Agent | Tier | Role |
|---|---|---|
| bosun | high | Orchestrator — delegates, plans, coordinates |
| lite | lite | Fast helper — quick edits, summaries |
| verify | medium | Validator — tests, builds, checks |
| scout | lite | Reconnaissance — explore, map structure |
| review | medium | Code review (read-only) |
| oracle | oracle | Deep reasoning — architecture, hard debugging |
| q | high | Executive assistant — tasks, projects, roadmaps |
Tiers map to models in config.toml. Change the model, not the agent.
MIT