byre/docs/architecture.md

Architecture

byre from the system down to its software layers. Open a box with the magnifier mark (Server Mac, byre serve, the Manager, Byre.app on Mac) to see the layer inside it. The diagram syntax is the diagrams knowledge-base article.

row
  user "You" "on your Macs and iPhone"
row
  mac "Byre.app on Mac" "SwiftUI · two panes" blue
  phone "Byre on iPhone" "same app, tab bar" blue
  icloud "iCloud" "CloudKit sync of app prefs" green
  dl "dl.byre.run" "Sparkle appcast + dmg" green
row
  tailnet "Tailscale tailnet" "each app and server is its own node · identity = auth"
row
  servermac "Server Mac" "launchd service run.fc.byre" amber
  vendors "Agent vendors" "Anthropic · OpenAI · Google" green
  origin "git remote" "origin: fetch · push" green
user -> mac
user -> phone
mac -> tailnet "REST · SSE · WebSockets"
phone -> tailnet
mac ..> icloud
mac ..> dl "updates"
tailnet -> servermac "HTTPS on byre's ts.net name"
servermac -> vendors "agent CLIs"
servermac -> origin "merge · push"

inside servermac
row
  service "byre serve" "Contents/Helpers/byre" amber
row
  clis "Agent CLIs" "one process group per session"
    claude_cli "claude"
    codex_cli "codex"
    agy_cli "agy"
  hands_srv "byre-hands" "screen · AX · Orion · Chrome, one copy per session"
row
  repos "Project checkouts" "default branch + task worktrees" green
  data "Data dir" "byre.db · loopback-token · codex home" green
service -> clis "spawn · stream-json / app-server"
clis -> service "MCP tools · hooks over loopback"
clis -> hands_srv "MCP stdio"
clis -> repos "edit · commit"
service -> repos "snapshots · merge"
service -> data

inside service
row
  listen "Listeners" "cmd/byre serve"
    tsnet "tsnet node" "Tailscale whois → user"
    loop "loopback 127.0.0.1" "bearer token, scripts"
row
  http "internal/server" "REST (api/openapi.yaml) · SSE hub · client & terminal WebSockets · preview ports" blue
  aside store "internal/store" "SQLite WAL, migrations" green
row
  mgr "internal/agents · Manager" "tasks · lead · reviews · workflows · merges" amber
row
  vendor "Vendor adapters" "one session per agent"
    claude "internal/claude" "stream-json"
    codex "internal/codex" "app-server JSON-RPC"
    agy "internal/antigravity" "stream-json · MCP proxy"
  tools "Agent-facing"
    mcp "internal/mcp" "byre tools over HTTP"
    hook "internal/hookcmd" "hooks via curl"
row
  infra "Infrastructure"
    git "internal/git" "worktrees · snapshots · notes"
    term "internal/terminal" "PTYs · OSC 133"
    clients "internal/clients" "client Mac requests"
    wf "internal/workflow · schedule · todo"
tsnet -> http
loop -> http
http -> mgr "start · message · merge"
mgr -> vendor
mgr -> tools
mgr -> infra
mgr -> store "writes"
store ..> http "events → SSE"
store ..> mgr "poke coordinator"

inside mgr
row
  coord "coordinator" "level-triggered, one goroutine" amber
  live "live sessions" "turns · inbox · turn-end commit"
row
  lead "lead agent" "per user · notes"
  tasks "tasks" "fork · subtasks · teams"
  review "reviews · audits" "workflow runs"
row
  workers "workers" "merge · push · snapshot · discard"
coord -> workers "start (in-progress column)"
live -> workers "turn end"
coord -> review
coord -> lead "deliveries"

inside mac
row
  ui "Views" "Panes · Chat · Composer · Sheet · Switcher" blue
row
  appstore "Store" "in-memory state of every task" amber
  pages "Pages" "WKWebView tabs · drive_page"
row
  stream "EventStream · EventCache" "SSE + per-server disk cache"
  remote "Remote" "client WebSocket: shell · files · hands · signing"
  fwd "Forwards" "*.localhost previews"
row
  net "API · TailnetProxy" "ByreAPI client over libtailscale SOCKS5"
  aside persist "Persistence · Updater" "SwiftData + CloudKit · Sparkle" green
ui -> appstore
ui -> pages
stream -> appstore "events"
appstore -> net "requests"
stream -> net
remote -> net
fwd -> net
pages ..> fwd

highlight "Event stream" store http tailnet stream appstore ui
highlight "Agent turn" mgr vendor clis tools hands_srv repos
highlight "Client Mac control" mgr clients http remote