agentrelay is a Python orchestration system for multi-agent coding workflows.
It models work as a dependency graph of tasks and emphasizes observable, file-based coordination.
📚 Full documentation site: https://duanegoodner.github.io/agentrelay/
The project is currently split into two layers:
src/agentrelay/(current architecture): core data model and interfaces (Task,TaskRuntime,Agent,AgentEnvironment)src/agentrelay/prototypes/v01/(working prototype): tmux + git worktree + signal-file orchestration
The core architecture is the long-term direction. End-to-end execution currently lives in prototypes/v01 while launcher/orchestrator integration is rebuilt around the new interfaces.
- Orchestrate dependent coding tasks with explicit state transitions
- Keep agent execution isolated via git worktrees and per-task branches
- Preserve a durable audit trail of task outcomes via filesystem artifacts
- Keep framework overhead low and favor debuggable Python primitives
- Immutable spec, mutable runtime:
Taskdescribes work;TaskRuntimetracks execution state. - Pluggable execution: framework and environment are configuration, not hard-coded behavior.
- Simple coordination: files and git are preferred over always-on services.
- Incremental evolution: prove behavior in prototypes, then promote stable abstractions.
src/agentrelay/- current architecture modulessrc/agentrelay/prototypes/v01/- runnable v01 prototype implementationtest/- tests for both current architecture and prototypegraphs/- example graph YAML definitionsdocs/- project docs and mkdocs site source
- Python 3.12+
- pixi
- git (with worktree support)
- tmux (for prototype execution)
- Claude Code (for prototype execution)
git clone https://github.com/duanegoodner/agentrelay.git
cd agentrelay
pixi installpixi run test # run tests
pixi run typecheck # pyright
pixi run format # black + isort
pixi run check # format + typecheck + tests
pixi run docs # serve docs locally