Chorus
The Agent Harness for AI-Human Collaboration, inspired by the AI-DLC (AI-Driven Development Lifecycle)
Install / Use
/learn @Chorus-AIDLC/ChorusQuality Score
Category
Development & EngineeringSupported Platforms
README
Chorus is an agent harness — the infrastructure that wraps around LLM agents to manage session lifecycle, task state, sub-agent orchestration, observability, and failure recovery. It lets multiple AI Agents (PM, Developer, Admin) and humans collaborate on a shared platform through the full workflow from requirements to delivery.
Inspired by the AI-DLC (AI-Driven Development Lifecycle) methodology. Core philosophy: Reversed Conversation — AI proposes, humans verify.
Table of Contents
- Why Agent Harness
- AI-DLC Workflow
- Screenshots
- Features
- Architecture
- Tech Stack
- Getting Started
- Skill Documentation
- Progress
- Documentation
- License
Why Agent Harness
An AI agent is only as reliable as the system around it. The model handles reasoning — but session boundaries, task state, context handoff, sub-agent coordination, and failure recovery all happen outside the model. That surrounding system is the agent harness.
Without a harness, agents drift across long tasks, lose context between sessions, duplicate work, and fail silently. A well-designed harness solves these problems:
| Harness Capability | The Problem It Solves | How Chorus Handles It | |---|---|---| | Session Lifecycle | Agents lose track of work across restarts | Every agent gets a persistent session with heartbeats; the plugin auto-creates and closes sessions on spawn/exit | | Task State Machine | No single source of truth for what's done | Tasks flow through a strict lifecycle — claimed, in progress, submitted, verified — visible to everyone in real time | | Context Continuity | Fresh context windows start from zero | Each check-in restores the agent's persona, current assignments, and project state so it can resume without re-discovery | | Sub-Agent Orchestration | Multi-agent work is chaotic without coordination | Lifecycle hooks wire up sub-agents automatically — sessions, context, and unblocked task discovery are handled, not hand-coded | | Observability | Can't debug what you can't see | Every action is logged with session attribution; Kanban and worker badges show who is doing what, live | | Failure Recovery | Stuck tasks block the entire pipeline | Idle sessions expire, orphaned tasks are released back to the pool, and any agent can pick them up again | | Planning & Decomposition | Agents jump into coding without a plan | A PM agent builds a dependency graph of tasks before execution begins — no work starts without an approved plan |
Chorus is not a framework — it doesn't provide building blocks for you to assemble. It is a complete harness with opinionated defaults: lifecycle hooks, ready-to-use MCP tools, role-based access, and a built-in human review loop.
AI-DLC Workflow
Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Verify ──> Done
^ ^ ^ ^ ^ ^
Human PM Agent PM Agent Dev Agent Admin Admin
creates analyzes drafts PRD codes & reviews closes
& plans & tasks reports & verifies
Three Agent roles:
| Role | Responsibility | MCP Tool Prefix |
|------|---------------|-----------------|
| PM Agent | Analyze Ideas, create Proposals (PRD + task breakdown), manage documents | chorus_pm_* |
| Developer Agent | Claim tasks, write code, report work, submit for verification | chorus_*_task, chorus_report_work |
| Admin Agent | Create projects/Ideas, approve Proposals, verify tasks, manage lifecycle | chorus_admin_* |
All roles share read-only and collaboration tools (chorus_get_*, chorus_checkin, chorus_add_comment, etc.).
Screenshots
Pixel Workspace — Real-time Agent Status
The left panel is a pixel workspace where pixel characters represent each Agent's real-time working status; the right panel shows live Agent terminal output.
Kanban — Real-time Task Flow
The Kanban board updates automatically as Agents work, with task cards flowing between To Do → In Progress → To Verify in real time.
Task DAG — Dependency Visualization
A directed acyclic graph showing task dependencies, clearly presenting execution order and parallel paths.
Proposal — AI Plan Review Panel
Proposals generated by the PM Agent contain document drafts and task DAG drafts. Admins review and approve or reject on this panel.
Requirements Elaboration — Structured Q&A
PM Agents clarify requirements through structured Q&A rounds before creating Proposals. The panel shows completed rounds with answers and pending follow-up questions for the stakeholder to answer.
Task Tracking — Details & Activity
The task detail panel integrates activity stream, comments, and dependencies, providing a complete record of each task's execution.
Universal Search — Cmd+K Command Palette
A Cmd+K command palette for searching across all 6 entity types (Tasks, Ideas, Proposals, Documents, Projects, Project Groups). Supports scope filtering (Global / Group / Project), filter tabs per entity type, and keyboard navigation. Both the Web UI and AI agents (via chorus_search MCP tool) share the same search backend.
Features
Kanban & Task DAG
Tasks support dependency relationships (DAG). The Kanban board displays task status and active Worker badges in real time. PMs define task execution order via dependsOnDraftUuids when creating Proposals.
Session Observability
Each Developer Agent creates a Session and checks in to tasks. The UI shows which Agent is working on which task in real time:
- Kanban cards display Worker badges
- Task detail panel shows active Workers
- Settings page manages Agents and Sessions
Multi-Agent Collaboration (Swarm Mode)
Supports Claude Code Agent Teams for parallel multi-Agent execution. The Team Lead assigns Chorus tasks to multiple Sub-Agents, each independently managing their own task lifecycle.
Chorus Plugin for Claude Code
The Claude Code plugin automates Session lifecycle management:
- SubagentStart — Automatically creates a Chorus Session
- TeammateIdle — Automatically sends heartbeats
- SubagentStop — Automatically checks out tasks + closes Session + discovers newly unblocked tasks
Requirements Elaboration
PM Agents clarify requirements through structured Q&A rounds before creating Proposals. Questions are categorized (functional, scope, technical, etc.) with multiple-choice options. Humans answer in CC terminal or on the Web UI. Proposals cannot be submitted until elaboration is resolved or explicitly skipped.
Proposal Approval Flow
The PM Agent creates a Proposal (containing document drafts and task drafts). After Admin approval, drafts materialize into actual Document and Task entities.
Notification System
In-app notifications with real-time SSE delivery and Redis Pub/Sub for cross-instance propagation:
- 10 notification types — task assigned/verified/reopened, proposal approved/rejected, comment added, etc.
- Per-user preferences — toggle each notification type on/off
- MCP tools —
chorus_get_notifications,chorus_mark_notification_readfor Agent access - Redis Pub/Sub — optional, enables SSE events across multiple ECS instances (ElastiCache Serverless)
@Mention
@mention support across comments and entity descriptions — users and AI agents can mention each other to trigger targeted notifications:
- Tiptap-based editor —
@autocomplete dropdown with user/agent search - Permission-scoped — users can mention all company users + own agents; agents follow same-owner rules
- Mention notifications —
action="mentioned"with context snippet and deep link to the source entity - MCP tool —
chorus_search_mentionablesfor agents to look up UUIDs before writing mentions
Activity Stream
Records all participant actions with Session attribution (AgentName / SessionName format), providing complete work audit trails.
Universal Search
Global search across Tasks, Ideas, Proposals, Documents, Projects, and Project Groups via a Cmd+K command palette. Features include:
- 3 scope levels — Global (company-wide), Group (project group), Project (single project), with smart default based on current page
- 6 entity types — filter by type via tabs, each showing Top 20 results
- Snippet generation — matched context extracted around the keyword hit
- MCP tool —
chorus_searchavailable to all agent roles - **Keyboard
