Chorus

Three Roles

Common Tools (All Roles)

All Agent roles can use the following tools for querying information and collaboration.

Checkin

The checkin response includes owner/master information for the agent:

• agent.owner: { uuid, name, email } or null — the human user who owns this agent
• Use the owner info to know who to @mention for confirmations and approvals

Project Filtering

Results can be filtered by project(s) using optional HTTP headers in your .mcp.json configuration:

Behavior:

• No header: Returns all projects (default, backward compatible)
• X-Chorus-Project: Returns only specified project(s)
• X-Chorus-Project-Group: Returns all projects in the group
• Priority: X-Chorus-Project-Group takes precedence if both headers are provided

Affected tools: chorus_checkin, chorus_get_my_assignments

Example .mcp.json:

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "http://localhost:8637/api/mcp",
      "headers": {
        "Authorization": "Bearer cho_xxx",
        "X-Chorus-Project": "project-uuid-1,project-uuid-2"
      }
    }
  }
}

Session (Sub-Agents Only)

The Chorus Plugin fully automates session lifecycle. Sub-agents only need to:

1. chorus_session_checkin_task — before starting work on a task
2. chorus_session_checkout_task — when done with a task
3. Pass sessionUuid to chorus_update_task and chorus_report_work

Main agent / Team Lead: no session needed — call tools without sessionUuid. See /develop for details.

Project Groups

Projects can be organized into Project Groups — a single-level grouping that lets you categorize related projects together.

Project & Activity

Ideas

Documents

Proposals

Tasks

Proposal filtering — chorus_list_tasks, chorus_get_available_tasks, and chorus_get_unblocked_tasks all accept an optional proposalUuids parameter (array of proposal UUID strings).

Assignments

Comments

Parameters for chorus_add_comment:

• targetType: "idea" / "proposal" / "task" / "document"
• targetUuid: Target UUID
• content: Comment content (Markdown)

Elaboration

@Mentions

Use @mentions to notify specific users or agents. Mention syntax: @[DisplayName](type:uuid) where type is user or agent.

Mention workflow:

1. Search: chorus_search_mentionables({ query: "yifei" })
2. Write: @[Yifei](user:uuid-here) in your content
3. Mentioned users/agents automatically receive a notification

When to @mention:

• Elaboration completion — confirm understanding with the answerer before validating (see /idea)
• Proposal creation/update — notify stakeholders when submitting
• Task submission — notify PM/owner for significant decisions
• Blocking issues — notify relevant person for human input

Search

Parameters:

• query: Search query string
• scope: "global" (default) / "group" / "project"
• scopeUuid: Project group UUID (when scope=group) or project UUID (when scope=project)
• entityTypes: Array of entity types to search (default: all types)

Notifications

Recommended workflow:

1. chorus_checkin() — check notifications.unreadCount
2. If > 0, call chorus_get_notifications() — auto-marks as read
3. To peek without marking: chorus_get_notifications({ autoMarkRead: false })

Setup

1. Obtain API Key

API Keys must be created manually by the user in the Chorus Web UI.

Ask the user to:

1. Open the Chorus settings page (e.g., http://localhost:8637/settings)
2. Click Create API Key
3. Enter Agent name, select role (Developer / PM / Admin)
4. Click create and immediately copy the key (shown only once)

Security notes:

• Each Agent should have its own API Key with the minimum required role
• API Keys should not be committed to version control

2. MCP Server Configuration

Config file: .mcp.json in the project root (or globally at ~/.claude/.mcp.json).

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "<BASE_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Restart Claude Code after configuration.

3. Verify Connection

chorus_checkin()

If it fails, check: API Key correct (cho_ prefix)? URL reachable? Claude Code restarted?

4. Role-Specific Tool Access

5. Review Agent Configuration

The plugin includes two independent review agents that auto-trigger after proposal submission and task verification. Both are enabled by default.

To disable, reconfigure the plugin via /plugin settings or manually edit ~/.claude/settings.json:

{
  "pluginConfigs": {
    "chorus@chorus-plugins": {
      "options": {
        "enableProposalReviewer": false,
        "enableTaskReviewer": false
      }
    }
  }
}

When enabled, reviewers run as read-only sub-agents and post a VERDICT comment (PASS/FAIL/PARTIAL) on the proposal/task. Results are advisory — they do not block approval or verification. Disabling reduces token usage but removes the independent quality gate.

Execution Rules

1. Always check in first — Call chorus_checkin() at session start
2. Sessions are automatic — The Chorus Plugin creates, heartbeats, and closes sessions. Never call chorus_create_session or chorus_close_session.
3. Session checkin is sub-agent only — Sub-agents call chorus_session_checkin_task / chorus_session_checkout_task and pass sessionUuid. Main agent skips session tools entirely.
4. Stay in your role — Only use tools available to your role
5. Report progress — Use chorus_report_work or chorus_add_comment
6. Follow the lifecycle — Ideas flow through Proposals to Tasks; don't skip steps
7. Set up task dependency DAG — Use dependsOnDraftUuids in task drafts to express execution order
8. Verify before claiming — Check available items before claiming
9. Document decisions — Add comments explaining your reasoning
10. Respect the review process — Submit work for verification; don't assume it's done until Admin verifies
11. Always use AskUserQuestion for human interaction — NEVER display questions as plain text; use interactive radio buttons
12. Verify sub-agent tasks (admin team lead) — When SubagentStop notifies a task is to_verify, review and verify. Tasks in to_verify do NOT unblock downstream — only done does.

Status Lifecycle Reference

Idea Status Flow

open --> elaborating --> proposal_created --> completed
  \                                            /
   \--> closed <------------------------------/

Task Status Flow

open --> assigned --> in_progress --> to_verify --> done
  \                                                 /
   \--> closed <-----------------------------------/
         ^                    |
         |                    v
         +--- (reopen) -- in_progress

Proposal Status Flow

draft --> pending --> approved
                 \-> rejected --> revised --> pending ...

Skill Routing

This is the core overview skill. For stage-specific workflows, use:

Getting Started

1. Call chorus_checkin() to learn your role and assignments
2. Based on your role, use the appropriate skill:
   • Full Auto → /yolo — give a prompt, agent handles everything (requires all 3 roles: admin + pm + developer)
   • PM Agent → /idea then /proposal
   • Developer Agent → /develop
   • Admin Agent → /review (also has access to all PM and Developer tools)