Daily Use

Patterns for everyday work with bosun.

Session lifecycle

Starting

just start              # Sandboxed session (recommended)
just start-unsandboxed  # Without bwrap
just attach             # Reattach to existing session

# Direct CLI equivalents
bosun start
bosun run
bosun attach [session]

During a session

Delegate work:

spawn_agent({ agent: "lite", task: "Summarize the auth module" })
spawn_agent({ agent: "verify", task: "Run all tests and report" })

Check who's working:

mesh_peers({})

Navigate tmux windows:

  • Alt+1, Alt+2, ... — switch to window by number
  • Alt+n — next window
  • Alt+p — previous window

Spawn agents from tmux keybindings (CLI-backed):

  • Ctrl+A n → bosun run --window
  • Ctrl+A N → bosun run

just recipes and tmux spawn keybindings now route through the same Bosun CLI.

Ending

Save context before stopping:

You: /handoff

Then:

just stop               # Closes everything
# or
bosun stop

Resuming

just start

You: /pickup

Select a handoff from the list. Context restored.

Planning

For non-trivial work (3+ files, multi-step), bosun creates a plan:

You: Add WebSocket support to the API

Bosun: This is complex. Let me plan first.
[Creates plan at workspace/users/.../plans/...]
[Opens in split pane for review]

Plans have phases with gate checks (verify → review → commit) between them.

Commands:

  • /handoff — save session context for later
  • /pickup — resume from a handoff
  • /fork — branch an exploration from current context

Common patterns

Explore, then implement

You: Clone github.com/org/repo and understand how auth works,
     then add OAuth2 support

Bosun will:

  1. Clone → spawn scout → get structure report
  2. Plan the OAuth2 implementation
  3. Delegate to lite for implementation
  4. Verify with tests

Review existing code

You: Review the changes in the last 3 commits for security issues

Bosun spawns review agent (read-only, won't modify code).

Deep debugging

You: This test is flaking — sometimes passes, sometimes fails.
     I need to understand why.

Bosun may spawn oracle for hard reasoning problems.

Parallel work

You: Write tests for the API while also updating the docs

Bosun spawns two agents, reserves files for each, coordinates results.

Configuration

config.toml

The single config file. Key sections:

[models]
lite = "<your-fast-model>"       # see config.sample.toml for examples
medium = "<your-balanced-model>"
high = "<your-best-model>"
oracle = "<your-reasoning-model>"

[env]
allowed = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", ...]  # passed into sandbox

[paths]
# Changes require `just stop && just start` (bwrap mounts are frozen at startup)
ro_bind = ["/path/to/other/repo"]     # read-only access from sandbox
rw_bind = ["/path/to/writable/dir"]   # read-write access from sandbox

[sandbox]
enabled = true                         # tool-level sandboxing (independent of bwrap)
gpu_passthrough = true                 # bind GPU render nodes + /sys into sandbox
# docker_passthrough = false           # bind Docker socket (opt-in, ≈ root on host)

[daemon]
enabled = true
heartbeat_interval_seconds = 30

[bash_readonly]
# network = false                        # Block TCP/UDP (default — most secure)
network = true                           # Allow network — agents need git, curl, etc.
# writable = ["/tmp"]                    # Paths writable inside bwrap sandbox

Agents use web_search and fetch_content tools via the pi-web-access extension. At least one provider key is required — without one, agents can't search the web.

[web_access]
gemini_api_key = "AIza..."              # Free tier at aistudio.google.com/apikey
# perplexity_api_key = "pplx-..."       # ~$5/mo at perplexity.ai/settings/api
# provider = "auto"                     # auto | perplexity | gemini

After adding or changing a key, run just init to regenerate ~/.pi/web-search.json, then restart pi (the extension caches the config in memory on startup).

Updating

just update     # Updates pi and all packages
just doctor     # Check environment health
bosun doctor    # Same checks via CLI
bosun init      # Regenerate .pi/*.json from config.toml

Troubleshooting

Agent won't spawn: Check mesh_peers() — is the mesh full? Check model config in config.toml.

Daemon not running: daemon({ action: "status" }). If stopped, restart with just start.

Sandbox blocking something: Check .pi/sandbox.json for read/write restrictions. Or use just start-unsandboxed temporarily.

Stale mesh state: If agents show as active but aren't, the mesh self-heals on next heartbeat. Or restart the session.