<p align="center">
  <img src="docs/images/chorus-slug.png" alt="Chorus" width="240" />
</p>

<p align="center"><strong>The Agent Harness for AI-Human Collaboration</strong></p>

<p align="center">
  <a href="https://discord.gg/SwcCMaMmR">
    <img src="https://img.shields.io/badge/Discord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord">
  </a>
  <a href="https://github.com/Chorus-AIDLC/Chorus/actions/workflows/test.yml">
    <img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/ChenNima/f245ebf1cf02d5f6e3df389f836a072a/raw/coverage-badge.json" alt="Coverage">
  </a>
</p>

<p align="center"><a href="README.zh.md">中文</a></p>

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.

Inspired by the **[AI-DLC (AI-Driven Development Lifecycle)](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/)** methodology. Core philosophy: **Reversed Conversation** — AI proposes, humans verify.

---

## 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
```

The labels under each stage are the **permissions** an actor needs at that stage — granted to a human, an Agent (preset or Custom), or both. There are no fixed roles; any combination of the 5 × 3 permission matrix is possible. See [`docs/PERMISSIONS.md`](docs/PERMISSIONS.md).

---

## What's New

**[v0.9.0](https://chorus-ai.dev/blog/chorus-v0.9.0-release/)** — Brainstorm skill for fuzzy ideas (open-ended chat before structured Q&A) and idea-completion reports (every shipped idea gets a Summary / Decisions / Follow-ups writeup, surfaced on the idea overview).

**[v0.8.0](https://chorus-ai.dev/blog/chorus-v0.8.0-release/)** — OpenSpec-aware mode (Claude Code): auto-activates when an `openspec/` directory and the `openspec` CLI are both present, adds `/opsx/{explore,propose,apply,archive}` and a post-verify archive-trigger hook.

**[v0.7.0](https://chorus-ai.dev/blog/chorus-v0.7.0-release/)** — Fine-grained agent permissions: 5 resources × 3 actions grid replaces the PM/Developer/Admin three-way choice, with presets + a Custom option for free combination.

**[v0.6.7](https://chorus-ai.dev/blog/chorus-v0.6.7-release/)** — Chorus plugin for Codex CLI (one-command installer), workspace picker when one email belongs to multiple Companies, per-client connect guides.

**[v0.6.6](https://chorus-ai.dev/blog/chorus-v0.6.6-release/)** — npm one-click install (`npx @chorus-aidlc/chorus`), document export (MD/PDF/Word), proposal revoke, faster agent checkin with work status at a glance.

**[v0.6.2](https://chorus-ai.dev/blog/chorus-v0.6.2-release/)** — Embedded PGlite mode (zero-dependency deployment), structured logging with Pino, stateless MCP for horizontal scaling, default port changed to 8637.

**[v0.6.1](https://chorus-ai.dev/blog/chorus-v0.6.1-release/)** — `/yolo` skill: full-auto AI-DLC pipeline (Idea → Proposal → Execute → Verify) with Agent Team parallel execution.

**[v0.6.0](https://chorus-ai.dev/blog/chorus-v0.6.0-release/)** — IdeaTracker dashboard, independent review agents (proposal-reviewer + task-reviewer), real-time agent presence indicators, cross-column Kanban animation.

> Full changelog: [CHANGELOG.md](CHANGELOG.md)

---

## Quick Start

Run Chorus locally with two commands — no database, no Docker, no config files needed.

```bash
npm install -g @chorus-aidlc/chorus
chorus
```

That's it. Chorus starts with an embedded PostgreSQL (PGlite), runs migrations automatically, and opens at **http://localhost:8637**.

> **Note:** PGlite is an embedded, single-process PostgreSQL — great for local single-user usage, but its connection handling has limits under concurrent load. If you plan to run multiple agents or users simultaneously, use an external PostgreSQL via `DATABASE_URL=postgresql://...` or the full [Docker Compose](#quick-start-with-docker-recommended) stack.

Default login: `admin@chorus.local` / `chorus`

### Options

```bash
# Custom port
chorus --port 3000

# Custom data directory (default: ~/.chorus-data)
chorus --data-dir /path/to/data

# Custom credentials
DEFAULT_USER=me@example.com DEFAULT_PASSWORD=secret chorus

# Use an external PostgreSQL instead of embedded PGlite
DATABASE_URL=postgresql://user:pass@host:5432/chorus chorus
```

### Other deployment options

| Method | Command |
|--------|---------|
| **npm** (simplest) | `npm i -g @chorus-aidlc/chorus && chorus` |
| **Docker (standalone)** | [`docker compose -f docker-compose.local.yml up`](#quick-start-with-docker-recommended) |
| **Docker (full stack)** | [`docker compose up`](#quick-start-with-docker-recommended) (PostgreSQL + Redis + Chorus) |
| **AWS CDK** | [Deploy to AWS](#deploy-to-aws) |

---

## Screenshots

### Proposal — AI Agent Generates Plans in Real Time

![Proposal Presence](docs/images/proposal-presence.gif)

Watch a PM Agent analyze requirements and generate a proposal with PRD and task DAG — with real-time presence indicators showing agent activity.

### Pixel Workspace — Real-time Agent Status

![Pixel Workspace](docs/images/pixcel-workspace-new.gif)

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

![Kanban Presence](docs/images/kanban-presence.gif)

The Kanban board updates automatically as Agents work, with task cards flowing between To Do → In Progress → To Verify in real time. Agent presence indicators highlight which resources are being worked on.

### Kanban & Task DAG

![Kanban & Task DAG](docs/images/kanan-dag.png)

Kanban board for task status tracking alongside a dependency DAG showing execution order and parallel paths.

### Idea & Requirements Elaboration

![Idea & Elaboration](docs/images/idea-elaborate.png)

PM Agents clarify requirements through structured Q&A rounds before creating Proposals. The panel shows idea details alongside completed elaboration rounds with answers and category tags.

### Proposal Review

![Proposal Review](docs/images/proposal.png)

Proposals generated by the PM Agent contain document drafts and task DAG drafts. Admins review and approve or reject on this panel.

### Acceptance Criteria — Dual-Path Verification

![Acceptance Criteria](docs/images/task-ac.png)

Dev Agent self-checks and Admin reviews each acceptance criterion independently, with structured pass/fail evidence for every item.

### Universal Search — Cmd+K Command Palette

![Universal Search](docs/images/universal-search.png)

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

- **Session Lifecycle** — Persistent sessions with heartbeats, auto-expiry, and failure recovery
- **Task DAG** — Dependency modeling, cycle detection, and interactive visualization
- **Kanban** — Real-time task flow with Worker badges and agent presence
- **Multi-Agent Collaboration** — Claude Code Agent Teams (Swarm Mode) for parallel execution
- **Fine-Grained Agent Permissions** — 5 resources × 3 actions grid with preset + custom combinations ([details](docs/PERMISSIONS.md))
- **Chorus Plugin** — Lifecycle hooks automate session create/close, heartbeats, and context injection
- **Requirements Elaboration** — Structured Q&A rounds before proposal creation
- **Proposal Approval Flow** — PM drafts, Admin approves, drafts materialize into real entities
- **Notifications** — In-app + SSE push + Redis Pub/Sub with per-user preferences ([design doc](src/app/api/notifications/README.md))
- **@Mention** — Tiptap autocomplete, permission-scoped search, mention notifications ([design doc](src/app/api/mentionables/README.md))
- **Activity Stream** — Full audit trail with session attribution
- **Universal Search** — Cmd+K across 6 entity types, 3 scope levels, snippet generation ([design doc](docs/SEARCH.md))
---

## Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                 Chorus — Agent Harness (:8637)                    │
│                                                                  │
│  ┌── Harness Capabilities ───────────────────────────────────┐   │
│  │  Session Lifecycle │ Task State Machine │ Context Inject   │   │
│  │  Sub-Agent Orchestration │ Observability │ Failure Recovery│   │
│  └───────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌── Chorus Plugin (lifecycle hooks) ────────────────────────┐   │
│  │  SubagentStart/Stop │ Heartbeat │ Skill & Context Inject  │   │
│  └───────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌── API Layer ──────────────────────────────────────────────┐   │
│  │  /api/mcp  — MCP Streaming (50+ tools, permission-gated)  │   │
│  │  /api/*    — REST API (Web UI + SSE push)                 │   │
│  └───────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌── Service Layer ──────────────────────────────────────────┐   │
│  │  AI-DLC Workflow │ UUID-first │ Multi-tenant              │   │
│  └───────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌── Web UI (React 19 + Tailwind + shadcn/ui) ──────────────┐   │
│  │  Kanban │ Task DAG │ Proposals │ Activity │ Sessions      │   │
│  └───────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────┘
     ↑              ↑              ↑              ↑
  Agent w/      Agent w/       Agent w/         Human
  idea+proposal  task:write    *:admin perms   (Browser)
   :write perms    perms      (proxy approval)
   (LLM)          (LLM)         (LLM)
                     │
          ┌──────────▼──────────┐   ┌─────────────────────┐
          │  PostgreSQL + Prisma │   │  Redis (optional)   │
          └─────────────────────┘   │  Pub/Sub for SSE    │
                                    └─────────────────────┘
```

### Packages

| Package | Description |
|---------|-------------|
| [`packages/openclaw-plugin`](packages/openclaw-plugin) | **OpenClaw Plugin** — Connects [OpenClaw](https://openclaw.ai) to Chorus via persistent SSE + MCP bridge. |
| [`packages/chorus-cdk`](packages/chorus-cdk) | **AWS CDK** — Infrastructure-as-code for deploying Chorus to AWS. |

## Tech Stack

| Component | Technology |
|-----------|-----------|
| Framework | Next.js 15 (App Router, Turbopack) |
| Language | TypeScript 5 (strict mode) |
| Frontend | React 19, Tailwind CSS 4, shadcn/ui (Radix UI) |
| ORM | Prisma 7 |
| Database | PostgreSQL 16 |
| Cache/Pub-Sub | Redis 7 (ioredis) — optional |
| Agent Integration | MCP SDK 1.26 (HTTP Streamable Transport) |
| Auth | OIDC + PKCE / API Key / SuperAdmin |
| i18n | next-intl (en, zh) |
| Deployment | [Docker Hub](https://hub.docker.com/repository/docker/chorusaidlc/chorus-app/general) / Docker Compose / AWS CDK |

---

## Getting Started

### Quick Start with Docker (Recommended)

No build tools or external databases required. The image bundles [PGlite](https://pglite.dev) (embedded PostgreSQL):

```bash
git clone https://github.com/Chorus-AIDLC/chorus.git
cd chorus

DEFAULT_USER=admin@example.com DEFAULT_PASSWORD=changeme \
  docker compose -f docker-compose.local.yml up -d
```

Open [http://localhost:8637](http://localhost:8637) and log in with the credentials above.

> Data is persisted in a Docker volume. The embedded mode is single-instance only (no Redis).

#### Production Deployment (PostgreSQL + Redis)

For production with multiple replicas:

```bash
DEFAULT_USER=admin@example.com DEFAULT_PASSWORD=changeme \
  docker compose up -d
```

> See [Docker Documentation](docs/DOCKER.md) for all environment variables and configuration options.

---

### Local Development

Prerequisites: Node.js 22+, pnpm 9+, Docker (for PostgreSQL/Redis)

```bash
cp .env.example .env
pnpm docker:db
pnpm install
pnpm db:migrate:dev
pnpm dev
# Open http://localhost:8637
```

### Local Development (no Docker)

Prerequisites: Node.js 22+, pnpm 9+

```bash
cp .env.example .env
pnpm install
pnpm dev:local        # Dev server on http://localhost:8637
```

PGlite runs embedded PostgreSQL on port 5433. Data stored in `.pglite/` — delete to reset.

### Deploy to AWS

```bash
./install.sh
```

The interactive installer provisions VPC, Aurora Serverless v2, ElastiCache Serverless, ECS Fargate, and ALB with HTTPS. Configuration saved to `default_deploy.sh` for re-deploys.

### Connect AI Agents

The fastest path is the in-app setup wizard: open the Web UI, go to **Settings → Setup Guide → Open setup guide**, and follow the step-by-step instructions for your client (Claude Code, Codex, OpenCode, OpenClaw, or other agents). The wizard creates the API key for you, shows the exact commands, and walks through verifying the connection.

If you'd rather read the full docs:

| Client | Guide |
|--------|-------|
| Claude Code | [CONNECT_CLAUDE_CODE.md](docs/CONNECT_CLAUDE_CODE.md) |
| Codex CLI | [CONNECT_CODEX.md](docs/CONNECT_CODEX.md) |
| OpenCode † | [CONNECT_OPENCODE.md](docs/CONNECT_OPENCODE.md) |
| Other MCP agents (Cursor, Continue, custom, …) | [CONNECT_OTHER_AGENTS.md](docs/CONNECT_OTHER_AGENTS.md) |

† OpenCode support is provided by the community-maintained [`opencode-chorus`](https://github.com/etnperlong/opencode-chorus) plugin (npm: [`opencode-chorus`](https://www.npmjs.com/package/opencode-chorus)), authored by [@etnperlong](https://github.com/etnperlong). Thanks!

Create API Keys in the Web UI under **Settings → Agents → Create API Key**. Keys start with `cho_` and are shown only once.

![Create API Key](docs/images/create-key.png)

---

## Skill Documentation

| Method | Location | Use Case |
|--------|----------|----------|
| **Plugin-embedded (Claude Code)** | `public/chorus-plugin/skills/` | Claude Code + Chorus plugin, automated Sessions and lifecycle hooks |
| **Plugin-embedded (Codex CLI)** | `plugins/chorus/skills/` | Codex CLI + Chorus plugin, ported skills with `$`-prefixed slash commands |
| **Standalone** | `public/skill/` (served at `/skill/`) | Any other MCP-capable Agent (Cursor, Continue, custom), manual Session management |

### OpenSpec mode (opt-in, plugin 0.8.1+)

PM agents that have the [OpenSpec](https://github.com/Fission-AI/OpenSpec)
CLI installed can author proposals in a structured `proposal.md` +
`design.md` + `specs/<capability>/spec.md` layout. Local files are the
working copy and Chorus `documentDrafts` are the mirror; reviewers see a
predictable shape (`## ADDED Requirements`, `### Requirement:`,
`#### Scenario:`) instead of free-form Markdown. A PostToolUse hook on
`chorus_admin_verify_task` injects an `openspec archive <slug>` reminder
when the last task of an OpenSpec idea is verified, so finalized specs
are merged into the long-term spec set right after sign-off. The mode is
strictly opt-in: when `openspec` is not installed, behavior is unchanged.
Master switch on Claude Code is `enableOpenSpec` (plugin userConfig,
default `true`); both clients also honor `CHORUS_OPENSPEC_MODE=off`. No
new MCP tools or schema changes ship in this mode; the canonical skill
reuses the existing `chorus_pm_*` draft and document tools, with mirror
calls routed through the `chorus-api.sh` wrapper to keep multi-thousand-
line markdown out of LLM context. See
[OPENSPEC_MODE.md](docs/OPENSPEC_MODE.md) for the full guide.

---

## Documentation

| Document | Description |
|----------|------------|
| [PRD](docs/PRD_Chorus.md) | Product Requirements Document |
| [Architecture](docs/ARCHITECTURE.md) | Technical Architecture Document |
| [MCP Tools](docs/MCP_TOOLS.md) | MCP Tools Reference |
| [Permissions](docs/PERMISSIONS.md) | Agent permission model (5 × 3 matrix, presets, Custom mode) |
| [Chorus Plugin](docs/chorus-plugin.md) | Plugin Design & Hook Documentation |
| [OpenSpec Mode](docs/OPENSPEC_MODE.md) | Opt-in OpenSpec authoring mode for PM agents (Plugin 0.8.1+) |
| [Search](docs/SEARCH.md) | Global Search Technical Design |
| [AI-DLC Gap Analysis](docs/AIDLC_GAP_ANALYSIS.md) | AI-DLC Methodology Gap Analysis |
| [AIG Implementation Plan](docs/CHORUS_AIG_PLAN.md) | Agent transparency roadmap |
| [Presence Design](docs/PRESENCE_DESIGN.md) | Real-time agent presence system |
| [Docker](docs/DOCKER.md) | Docker image usage & deployment |
| [Logging](docs/LOGGING.md) | Structured logging architecture |
| [CLAUDE.md](CLAUDE.md) | Development Guide |

---

## License

AGPL-3.0 — see [LICENSE.txt](LICENSE.txt)
