Page
choir-agent
The Choir container runtime. A single Go binary that runs inside Docker containers, managing dual-lane cognition, tool execution, and skill orchestration.
Architecture
choir-agent (single process)
├── Edge lane — goroutine, fast model, user-facing
├── Core lane — goroutine, flagship model, deep reasoning
├── Arbiter — goroutine, serializes all committed side effects
├── Lock manager — S/X resource locks, atomic lockset
├── Tool executor — 14 built-in + external tools
├── Skill engine — deterministic state machine orchestration
├── Secret store — in-memory only, per-tool scoping
├── RPC client — heartbeat, secrets, approvals via choird
└── Working memory — event window, reference summary, compaction
Container Filesystem
/choir/ (read-only, image-baked)
tools/global/ shared tool executables
tools/agent/ agent-specific tools
skills/ skill definitions
USER.md user identity (edge lane)
SOUL.md edge personality
SOUL-CORE.md core personality
bin/git-cred-helper credential helper symlink
version.json build metadata
/workspace/ (writable, bind-mounted)
.choirtmp/send/ agent -> choird file staging
.choirtmp/recv/ choird -> agent file staging
Built-In Tools
| Tool | Lock | Host? | Description |
|---|---|---|---|
| choir.exec | workspace:X | no | Shell execution |
| choir.fs.read | file:S | no | Read file |
| choir.fs.write | file:X | no | Edit file |
| choir.fs.search | file:S | no | Ripgrep search |
| choir.tts.speak | choirtmp:X | no | Text-to-speech |
| choir.web.search | none | no | Brave Search |
| choir.web.browse | browser_tab:X | yes | Playwright browsing |
| choir.notion.query | none | no | Notion API |
| choir.email.send | none | no | SMTP send |
| choir.email.receive | none | no | IMAP fetch |
| choir.email.check | none | no | IMAP check |
| choir.memory.query | none | yes | Memory search |
| choir.memory.upsert | none | yes | Knowledge write |
| choir.memory.compact | none | no | Force compaction |
Credential Helper Mode
When invoked as git-cred-helper (via argv[0] detection), the binary acts as a git credential helper, reading credentials from the mounted git credential secret file, validating the requested host, and parsing either username:password or token-only secret formats.