How andrealaforgia/relay-agentic-framework works
Relay turns an owner’s problem into acceptance-tested, review-gated delivery increments. The CLI connects the owner to persistent chat, while a deterministic coordinator replays the event ledger, dispatches workers, and applies gates; AI runners perform role-specific analysis and implementation. Evidence execution, review, and ledger auditing are distinct safeguards before checkpoints or PRs. The README documents additional learn, planning, monitoring, usage, and Codex-review capabilities. Sampled source confirms coordinator, bus, runner, review, audit, and Git operations; unsampled subsystem links are limited to documented behavior.
Main entry points: publisher.py Redis stream bus · coordinator/main.py Coordinator · cli/main.py Relay CLI · reader.py Event ledger
Components 23
Owner interaction
- Relay CLI
src/relay/cli/main.py - Interpreter chat
src/relay/cli/main.py - Curated knowledge
src/relay/cli - Live watch
src/relay/cli/watch.py
Deterministic coordination
- Coordinator
src/relay/coordinator/main.py - Dispatcher and gates
src/relay/coordinator/dispatcher.py - State projection
src/relay/coordinator/projection.py - Gate policy
src/relay/coordinator/policy.py
Worker delivery
- Role workers
src/relay/workers/chain.py - Expectation preparation
src/relay/workers/preparation.py - AI runners
src/relay/runners/base.py
Evidence and assurance
- Toolgate execution
src/relay/workers/toolgate.py - Evidence replay
src/relay/workers/evidence_replay.py - Review delivery
src/relay/workers/reviews.py
Ledger and integrations
- Message contract
src/relay/contract/validator.py - Redis stream bus
src/relay/bus/publisher.py - Event ledger
src/relay/ledger/reader.py - Ledger audit
src/relay/ledger/audit.py - Git and PR operations
src/relay/gitops/pr.py
Other components
- Owner
- Claude / Codex
- Redis
- Project repository
Connections 29
- Owner → Relay CLI: runs commands
- Relay CLI → Interpreter chat: opens session
- Interpreter chat → Redis stream bus: publishes messages
- Relay CLI → Curated knowledge: starts learning
- Relay CLI → Live watch: shows activity
- Coordinator → Event ledger: replays events
- Event ledger → State projection: supplies events
- Coordinator → State projection: applies events
- Coordinator → Dispatcher and gates: reacts to state
- Dispatcher and gates → Gate policy: checks gates
- Dispatcher and gates → Redis stream bus: dispatches work
- Role workers → Redis stream bus: consumes requests
- Role workers → AI runners: runs role turn
- AI runners → Claude / Codex: invokes model
- Expectation preparation → Claude / Codex: prepares expectations
- Role workers → Expectation preparation: handles preparation
- Coordinator → Toolgate execution: dispatches gates
- Toolgate execution → Project repository: runs pinned checks
- Toolgate execution → Evidence replay: records execution
- Role workers → Review delivery: validates reviews
- Review delivery → Event ledger: reads review context
- Review delivery → Redis stream bus: publishes review
- Redis stream bus → Message contract: validates messages
- Redis stream bus → Redis: reads and writes
- Event ledger → Redis: reads stream
- Relay CLI → Ledger audit: audits ledger
- Ledger audit → Event ledger: scans entries
- Coordinator → Git and PR operations: manages branches and PRs
- Git and PR operations → Project repository: updates repository