Chorus — Summary

Chorus is an agent harness for AI-human collaboration built around the AI-DLC (AI-Driven Development Lifecycle) methodology, described as infrastructure that wraps around LLM agents to manage session lifecycle, task state, sub-agent orchestration, observability, and failure recovery. It operates as a full-stack Next.js web application with a PostgreSQL backend (or embedded PGlite for single-user deployments) that provides a Kanban board, Task DAG visualization, proposal approval flows, and an MCP server (50+ tools) that AI agents connect to. The core philosophy is "Reversed Conversation" — AI proposes, humans verify — embodied in a 5-resource × 3-action permission matrix that controls what agents can do at each lifecycle stage. The framework includes a chorus CLI binary, lifecycle hooks via a Claude Code plugin, a Codex CLI plugin, and an OpenSpec-aware mode that auto-activates when an openspec/ directory is present.

Compared to seeds, Chorus is closest to claude-conductor in being a markdown-scaffold collaboration layer, but differs fundamentally: where claude-conductor is a minimal template bundle with no server, Chorus is a full production web application with PostgreSQL, Redis, a 50+-tool MCP server, real-time presence indicators, Kanban/DAG views, and a permission model — making it the most infrastructure-heavy framework in this batch.

Chorus — Overview

Origin

Developed by Chorus-AIDLC. Current version: 0.9.0. Inspired by AWS's AI-Driven Development Lifecycle (AI-DLC) methodology.

Core Philosophy

From the 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 (with fine-grained, configurable permissions) and humans collaborate through the full workflow from requirements to delivery."

Reversed Conversation principle: "AI proposes, humans verify" — the agent generates proposals, humans approve or reject, and only approved proposals materialize into real entities.

AI-DLC Workflow

Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Verify ──> Done
  ^          ^               ^                     ^          ^         ^
Human     idea:write     proposal:write         task:write   *:admin    *:admin
creates   + elaborate    + drafts                + reports   + verifies + closes

Permission Model

5 resources × 3 actions grid: idea, proposal, task, document, and * (admin) — each with read, write, and admin permissions. Any combination possible via "Custom" option.

OpenSpec Integration

v0.8.0 introduced OpenSpec-aware mode: auto-activates when both an openspec/ directory and the openspec CLI are present, adding /opsx/{explore,propose,apply,archive} commands and a post-verify archive hook.

Tech Stack

Chorus — Architecture

Distribution

• Type: npm package (@chorus-aidlc/chorus) + Docker image
• Version analyzed: 0.9.0
• License: AGPL-3.0
• Install options:
  • npm install -g @chorus-aidlc/chorus && chorus (embedded PGlite, no external deps)
  • docker compose -f docker-compose.local.yml up (standalone Docker)
  • docker compose up (full stack: PostgreSQL + Redis + Chorus)
  • AWS CDK deployment via packages/chorus-cdk
• Default port: 8637

Repository Layout

src/                        # Next.js App Router application
├── app/api/mcp/            # MCP streaming endpoint (50+ tools)
├── app/api/*/              # REST API endpoints
└── ...

plugins/chorus/             # Claude Code + Codex plugin
├── hooks.json              # SessionStart, PostToolUse lifecycle hooks
├── hooks/
│   ├── on-session-start.sh     # Checkin + OpenSpec detection
│   ├── on-post-submit-proposal.sh
│   ├── on-post-submit-for-verify.sh
│   ├── on-post-verify-task.sh
│   └── chorus-mcp-call.sh  # MCP tool invocation helper
├── skills/                 # Chorus workflow skills

.claude/                    # Claude Code integration
├── settings.json           # Plugin enablement
├── commands/               # Slash commands
│   ├── opsx/               # OpenSpec-aware commands
│   ├── openspec-*/         # OpenSpec workflow
│   └── ...
└── skills/                 # Chorus skills

openspec/                   # Optional OpenSpec integration directory
packages/
├── chorus-cdk/             # AWS CDK deployment package
├── openclaw-plugin/        # OpenClaw persistent SSE + MCP bridge
└── landing/                # Marketing landing page

prisma/                     # Prisma ORM schema + migrations

Config Files

• docker-compose.yml / docker-compose.local.yml — Docker deployment
• prisma/schema.prisma — database schema
• Environment variables: DATABASE_URL, CHORUS_URL, CHORUS_API_KEY, DEFAULT_USER, DEFAULT_PASSWORD

Required Runtime

• Node.js + pnpm (for development)
• Docker (for production deployment)
• PostgreSQL 16 (external) or PGlite (embedded)
• Redis 7 (optional, for Pub/Sub notifications)

Chorus — Components

CLI Binary: chorus

The npm package ships a chorus binary (chorus.mjs):

• chorus — start the server (with embedded PGlite)
• chorus --port 3000 — custom port
• chorus --data-dir /path/to/data — custom data directory
• With DATABASE_URL=... env var — use external PostgreSQL

Web UI Features

• Kanban board — real-time task flow with Worker badges and agent presence
• Task DAG — dependency visualization with cycle detection
• Proposal approval — PM Agent drafts, Admin approves/rejects
• Idea elaboration — structured Q&A rounds before proposal creation
• Pixel workspace — pixel characters showing each agent's real-time working status
• Activity stream — full audit trail with session attribution
• Universal Search — Cmd+K across 6 entity types (Tasks, Ideas, Proposals, Documents, Projects, Project Groups)
• Notifications — in-app + SSE push + Redis Pub/Sub with per-user preferences
• @Mention — Tiptap autocomplete, permission-scoped search

MCP Tools (50+)

The /api/mcp endpoint exposes 50+ tools, permission-gated:

• chorus_checkin — session check-in
• chorus_create_session, chorus_close_session — session management
• chorus_pm_submit_proposal — PM agent submits proposal
• chorus_submit_for_verify — developer submits task for verification
• chorus_admin_verify_task — admin verifies a task
• chorus_pm_add_document_draft, chorus_pm_update_document_draft, chorus_pm_update_document — document management
• chorus_get_notifications — fetch notifications
• chorus_search — universal search
• And 40+ more task/idea/proposal/document CRUD tools

Claude Code Plugin (in plugins/chorus/)

Hooks (hooks.json)

• SessionStart — on-session-start.sh: calls chorus_checkin, injects context, detects OpenSpec mode
• PostToolUse (matcher: chorus_pm_submit_proposal) — on-post-submit-proposal.sh: triggers proposal review agent
• PostToolUse (matcher: chorus_submit_for_verify) — on-post-submit-for-verify.sh: triggers task reviewer
• PostToolUse (matcher: chorus_admin_verify_task) — on-post-verify-task.sh: handles verification completion

Skills (.claude/skills/)

AWS CDK Package

packages/chorus-cdk — infrastructure-as-code for deploying Chorus to AWS (ECS, RDS, ElastiCache).

OpenClaw Plugin

packages/openclaw-plugin — connects OpenClaw AI to Chorus via persistent SSE + MCP bridge.

Chorus — Uniqueness

Differs from Seeds

Chorus is most adjacent to claude-conductor among the seeds in providing a human-AI collaboration layer with structured task tracking. However, where claude-conductor is a minimal markdown scaffold bundle with zero server infrastructure, Chorus is a full production web application: PostgreSQL/PGlite, Redis pub/sub, 50+ MCP tools, real-time Kanban and Task DAG UI, proposal approval flows, and a 5×3 permission matrix enforced at the API level. The "Reversed Conversation" (AI proposes, humans verify) philosophy is a direct inversion of most other frameworks in the batch where humans initiate work. Compared to taskmaster-ai (MCP-anchored, file-based tasks), Chorus uses a relational database and provides a web UI, making it the only framework in this batch with a full-stack production-grade deployment story.

Distinctive Position

1. Only framework with a web dashboard (beyond monitoring) — the UI is the primary human control plane, not an afterthought
2. Permission matrix enforced server-side — the 5×3 resource × action grid prevents agents from exceeding authorized actions at the API level, not via prompt instructions
3. Task DAG with cycle detection — dependency-aware task scheduling in a relational store
4. Reversed Conversation: AI proposes, humans verify — the only framework in this batch where human approval is the design center rather than an optional gate
5. OpenSpec-aware mode: native integration with the openspec CLI detected at session start

Explicit Anti-Patterns

• Hand-typing JSON content for document mirror MCP calls in OpenSpec mode (must use json_encode_file)
• Creating sub-agents with custom agent_type names (rejected by Codex 0.125 which only has default/explorer/worker)
• Not closing agents after wait_agent (completed ≠ closed; 6 concurrent max)

Observable Failure Modes

• AGPL-3.0 license: copyleft requirements may block proprietary adoption
• PGlite single-instance limit: not suitable for concurrent multi-agent/multi-user without external PostgreSQL
• Session heartbeat expiry: silent agents lose their session (must be handled at the agent skill level)
• Proposal-reviewer spawning via Codex is complex (6-agent cap, specific API constraints documented in hook)

Inspired By

AWS AI-DLC (AI-Driven Development Lifecycle) methodology, OpenSpec.