Documentation

Everything you need to install, configure, and run Chorus.

Installation

Chorus requires Node.js 18+, Python 3.8+, Git, and CodeRabbit installed on your system.

CodeRabbit handles automated code review. Install it on your GitHub or Azure DevOps repository before running Chorus, the self-review loop depends on it.

macOS

1. Install Node.js (if you don't have it):

# Using Homebrew
brew install node

# Or download from https://nodejs.org

2. Install Python 3.8+ (if you don't have it):

# Using Homebrew
brew install python@3

3. Install Chorus globally:

npm install -g chorus

The post-install script automatically creates a Python virtual environment at ~/.config/chorus/.venv and installs the required Python dependencies.

To skip the automatic Python setup (e.g. in CI), set CHORUS_SKIP_POSTINSTALL=1 before installing.

Windows

1. Install Node.js from nodejs.org (LTS recommended).

2. Install Python 3.8+ from python.org. Make sure to check "Add Python to PATH" during installation.

3. Open PowerShell or Command Prompt and install Chorus:

npm install -g chorus

The Python virtual environment is created at %USERPROFILE%\.config\chorus\.venv.

If you see permission errors, run your terminal as Administrator or use npm config set prefix to change the global install directory.

Setup

After installing, run the interactive setup:

chorus setup

This walks you through:

1. Provider — Choose GitHub (default) or Azure DevOps, then enter your repository details.
2. Authentication — Sign in with your Chorus account (email + password). Your API key is stored locally at ~/.config/chorus/.env.
3. Messenger — Choose Teams (default) or Slack for QA conversations. See Slack integration for details.

Configuration is saved to ~/.config/chorus/.env. You can re-run chorus setup at any time to reconfigure.

Running Chorus

Process your latest assigned issue:

chorus run

Process a specific issue by number:

chorus run 4464

Process from a full URL (auto-detects provider):

# GitHub
chorus run https://github.com/myorg/myrepo/issues/4464

# Azure DevOps
chorus run https://dev.azure.com/myorg/myproject/_workitems/edit/456

What happens when you run:

Fetches the issue and generates clarifying questions
Chats with QA via Teams/Slack to gather requirements
Generates and writes the code solution
Lints, reviews, and iterates on the changes
Creates a pull request once you approve

Flags & Options

Flag Description
--super Use Claude Opus 4.6 instead of Sonnet for the QA evaluation step. Produces higher-quality requirements at the cost of more credits (8x).
--skip-qa Skip the QA conversation entirely and go straight to the coding phase. Useful when the issue description already has enough detail.
--qa 'Name' Specify the QA contact by name for the chat. Chorus will message this person on Teams or Slack.
--model <name> Choose the AI model for the session. See the Models section for the full list of free and paid options.
--free Use the best free model (GPT-OSS 120B). Can be combined with --model to pick a different free model. Errors if combined with a paid model.

Examples

# Use Opus for higher-quality QA
chorus run 4464 --super

# Skip QA, jump straight to coding
chorus run 4464 --skip-qa

# Specify who to message for QA
chorus run 4464 --qa 'John Doe'

# Use the best free model (GPT-OSS 120B)
chorus run 4464 --free

# Pick a specific free model
chorus run 4464 --free --model qwen-coder

# Use a specific paid model
chorus run 4464 --model deepseek

# Combine flags
chorus run 4464 --super --model gemini --qa 'John Doe'

Models

Chorus supports a range of AI models. Use --free to default to the best free model, or --model <name> to pick one explicitly.

Free Models

These models are available at no extra cost via OpenRouter's free tier.

Flag value Model
gpt-oss GPT-OSS 120B default with --free
gpt-oss-20b GPT-OSS 20B
qwen-coder Qwen3 Coder 480B
qwen Qwen3 Next 80B
llama Llama 3.3 70B
hermes Hermes 3 405B
nemotron Nemotron 3 Nano 30B
gemma Gemma 3 27B
mistral Mistral Small 3.1 24B
glm GLM 4.5 Air
step Step 3.5 Flash
solar Solar Pro 3

Paid Models

These models consume credits from your Chorus account.

Flag value Model
claude Claude
chatgpt ChatGPT
deepseek DeepSeek
kimi Kimi
gemini Gemini
grok Grok
command-r Command R
Using --free with a paid model (e.g. --free --model deepseek) will error. Drop the --free flag to use paid models.

Environment Variables

These are stored in ~/.config/chorus/.env and set automatically during chorus setup. You can edit them manually if needed.

GitHub

GITHUB_OWNER GitHub org or username
GITHUB_REPO Repository name
GITHUB_TOKEN Personal access token (required for private repos)

Azure DevOps

AZDO_ORG Organization name
AZDO_PROJECT Project name
AZDO_REPO Repository name
AZDO_PAT Personal access token (required)
PROVIDER Set to azuredevops to force Azure DevOps provider

Messenger

MESSENGER teams (default) or slack
SLACK_BOT_TOKEN Slack bot token (required when using Slack)

Advanced

QA_MAX_ROUNDS Max QA conversation rounds (default: 5)
QA_POLL_INTERVAL Seconds between checking for replies (default: 60)
QA_POLL_TIMEOUT Timeout in seconds for QA response (default: 1800)
CODER_SAFE_MODE Set to 1 to require approval before file writes
CHORUS_SKIP_POSTINSTALL Set to 1 to skip Python setup during install

GitHub Integration

GitHub is the default provider for issue tracking and pull request creation. Chorus reads issues, creates branches, and opens PRs directly in your repo.

1. Create a Personal Access Token

Go to github.com/settings/tokens and generate a Fine-grained or Classic token with these permissions:

  • Issues — Read
  • Contents — Read & Write
  • Pull Requests — Read & Write

2. Configure Chorus

Run chorus setup and select GitHub when prompted for provider. Enter your owner, repo, and token.

Or set it manually in ~/.config/chorus/.env:

PROVIDER=github
GITHUB_OWNER=your-org
GITHUB_REPO=your-repo
GITHUB_TOKEN=ghp_your-token-here

3. Run

# By issue number
chorus run 4464

# By full URL
chorus run https://github.com/myorg/myrepo/issues/4464

Microsoft Teams Integration

Teams is the default messenger for QA conversations. Chorus sends clarifying questions to your QA contact via Teams chat and waits for their replies. No bot registration required — it uses the Microsoft Graph API with delegated permissions.

Setup

Teams is selected by default during chorus setup. During the QA phase, Chorus authenticates with Microsoft Graph using your organization's credentials to send and receive messages.

To explicitly set Teams as the messenger in ~/.config/chorus/.env:

MESSENGER=teams

Usage

# Chorus will message your QA contact on Teams
chorus run 4464 --qa 'John Doe'

Chorus sends John Doe a Teams message with clarifying questions and polls for replies until the QA round is complete.

Slack Integration

Use Slack instead of Teams for QA conversations. Chorus messages your QA contact via direct message and waits for their reply.

1. Create a Slack App

Go to api.slack.com/apps and click Create New App → From scratch.

Give it a name (e.g. "Chorus") and select your workspace.

2. Add OAuth Scopes

Under OAuth & Permissions, add these Bot Token Scopes:

Scope Purpose
chat:write Send messages to users
users:read Look up users by name
im:history Read DM replies
im:write Open DM channels

3. Install & Copy Token

Click Install to Workspace and authorize the app.

Copy the Bot User OAuth Token (starts with xoxb-).

4. Configure Chorus

Run chorus setup and select Slack when prompted for messenger. Paste your bot token when asked.

Or set it manually in ~/.config/chorus/.env:

MESSENGER=slack
SLACK_BOT_TOKEN=xoxb-your-token-here

5. Run with Slack

chorus run 4464 --qa 'John Doe'

Chorus will DM "John Doe" on Slack with clarifying questions and wait for their replies.

Azure DevOps Integration

Use Azure DevOps instead of GitHub for issue tracking and pull request creation.

1. Create a Personal Access Token

In Azure DevOps, go to User Settings → Personal access tokens → New Token.

Grant these scopes:

  • Work Items — Read
  • Code — Read & Write
  • Pull Request — Read & Write

2. Configure Chorus

Run chorus setup and select Azure DevOps when prompted for provider.

Or set it manually in ~/.config/chorus/.env:

PROVIDER=azuredevops
AZDO_ORG=your-org
AZDO_PROJECT=your-project
AZDO_REPO=your-repo
AZDO_PAT=your-personal-access-token

3. Run

# By work item number
chorus run 456

# By full URL (auto-detects Azure DevOps)
chorus run https://dev.azure.com/myorg/myproject/_workitems/edit/456

Chorus fetches the work item, runs the full QA + coding workflow, and creates a pull request in your Azure DevOps repo. Commits are automatically linked with AB#456 syntax.

CodeRabbit

Chorus depends on CodeRabbit for automated code review. During the self-review loop, Chorus pushes code and waits for CodeRabbit's review comments, then iterates on the feedback before opening the final PR.

1. Install CodeRabbit

Install CodeRabbit on your repository from the GitHub Marketplace or via the CodeRabbit dashboard for Azure DevOps.

CodeRabbit must be active on the same repository that Chorus creates pull requests in.

2. How it works

When Chorus creates a draft PR during its self-review phase:

  • CodeRabbit automatically reviews the changes and posts comments
  • Chorus reads the review feedback and addresses each comment
  • This loop repeats up to 3 iterations until the review passes cleanly
CodeRabbit must be installed and active on your repository before running Chorus. Without it, the self-review step will be skipped.