Choir

An LLM agent orchestration system for personalized agents with infrastructure-grade architecture.

Philosophy: Deterministic outer control plane + stochastic inner cognition — the LLM proposes, the control plane decides.

Table of Contents

• Architecture
• Components
• Quick Start
• Documentation
• Full Design
• License

Architecture

User(s) ─── Telegram (multi-bot, multi-DM) ───► choird (host daemon)
                                                   ├── gateway (routing, permissions)
                                                   ├── control plane (lifecycle, policy)
                                                   ├── memory module ──► Postgres + pgvector
                                                   ├── approval pipeline
                                                   └── transport (UDS / HTTP)
                                                         │
                                                         ▼
                                                  Docker container
                                                   └── choir-agent (single Go binary)
                                                         ├── Edge lane (fast, user-facing)
                                                         ├── Core lane (deep reasoning)
                                                         ├── Arbiter (event-sourced commit log)
                                                         ├── Lock manager
                                                         ├── Tool executor (14 built-in tools)
                                                         └── Skill engine (state machines)

Components

Component	Description
choird	Host daemon — control plane, Telegram gateway, container lifecycle, memory, approvals
choirctl	Stateless CLI — admin interface to choird
choir-agent	Container runtime — dual-lane cognition, tools, skills, locks

Quick Start

# 1. Install dependencies, reconcile ~/.choir.d/, and refresh binaries if versions changed
bash install.sh

# 2. Edit configuration
$EDITOR ~/.choir.d/config.json

# 3. Set secrets in ~/.choir.d/secrets.json (via choirctl)
echo 'sk-...' | choirctl secret set openrouter-key
echo '12345:TOKEN' | choirctl secret set telegram-bot-token
choirctl secret apply

# 4. Validate local config and secrets
choirctl config validate

# 5. Initialize the shared base repo scaffold
choirctl agent base init

# 6. Start choird
choirctl daemon start

# 7. Create and start an agent
choirctl agent init my-agent
choirctl agent build my-agent
choirctl agent start my-agent --dm=admin

Documentation

• Architecture — components, data flow, trust boundaries
• Getting Started — prerequisites, setup, first agent
• Configuration — config.json reference
• Commands — choirctl command reference
• Gateway — Telegram bot setup and commands
• Memory — 4-tier memory architecture
• Tools — tool system and built-in tools
• Skills — skill system and state machines
• Security — container hardening and secret management
• Development — building from source, contributing

Full Design

See DESIGN.md for the complete design specification.

License

MIT — see LICENSE in the repository.