Council

A terminal CLI for multi-model plan review. Get your plans reviewed by multiple LLMs in parallel via OpenCode.

Works with: Claude Code, OpenCode, or standalone terminal use.

What is Council?

Council is a CLI tool that enables AI coding assistants to get independent feedback on their plans from other AI models. When you're in plan mode or have a document you want reviewed, Council sends it to multiple models simultaneously (e.g., Gemini-3-Pro and GPT-5.2), collects their verdicts and feedback, and lets the assistant synthesize the results.

Council supports iterative refinement - the assistant can orchestrate multiple rounds of review until all models reach consensus, with anti-laziness checks to ensure thorough feedback.

Why Use Council?

• Diverse perspectives: Different models catch different issues
• Parallel execution: All reviewers run simultaneously for speed
• Iterative refinement: Multiple rounds until consensus
• Assistant remains in control: Reviewers are peers, not blockers
• Multi-turn support: If reviewers ask clarifying questions, continue the conversation
• Session persistence: Review sessions are saved with full round history
• Works everywhere: Claude Code, OpenCode, or direct terminal use

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                           USER REQUEST                              │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
    ┌───────────────────────────┐   ┌───────────────────────────┐
    │       CLAUDE CODE         │   │        OPENCODE           │
    │    (invokes /council)     │   │    (invokes /council)     │
    └─────────────┬─────────────┘   └─────────────┬─────────────┘
                  │                               │
                  └───────────────┬───────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          COUNCIL CLI                                │
│                                                                     │
│   ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐   │
│   │    Model A      │   │    Model B      │   │    Model N      │   │
│   │   (OpenCode)    │   │   (OpenCode)    │   │   (OpenCode)    │   │
│   └────────┬────────┘   └────────┬────────┘   └────────┬────────┘   │
│            │                     │                     │            │
│            └─────────────────────┼─────────────────────┘            │
│                                  ▼                                  │
│                    ┌─────────────────────┐                          │
│                    │     JSON OUTPUT     │                          │
│                    │  (with round number)│                          │
│                    └─────────────────────┘                          │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   ASSISTANT EVALUATES FEEDBACK                      │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
                          ┌───────────────┐
                          │   CONSENSUS   │
                          │   REACHED?    │
                          └───────┬───────┘
                                  │
                     ┌────────────┴────────────┐
                     │                         │
                    NO                        YES
                     │                         │
                     ▼                         ▼
          ┌──────────────────┐      ┌──────────────────┐
          │   REVISE PLAN    │      │      DONE        │
          └────────┬─────────┘      └──────────────────┘
                   │
                   └──────────────► (back to Council CLI)

Prerequisites

Council requires OpenCode CLI to be installed and authenticated:

• OpenCode CLI: Installation guide

Verify it's installed:

which opencode

Installation

1. Clone the repository

git clone https://github.com/bytes032/council.git
cd council

2. Install dependencies

bun install

3. Link globally

bun link

4. Run setup

Choose your setup based on which tool(s) you use:

# For Claude Code users
council setup --claude

# For OpenCode users
council setup --opencode

# For both
council setup --both

This installs:

• Claude Code: Session hook, settings configuration, and /council skill
• OpenCode: Session plugin and /council skill

Usage

CLI Commands

# Install for your tool(s)
council setup --claude     # Claude Code only
council setup --opencode   # OpenCode only
council setup --both       # Both tools

# Review a file (uses most recent ~/.claude/plans/*.md if not specified)
council review
council review ~/path/to/plan.md

# Review with anti-laziness check (press for thorough confirmation)
council review --press plan.md

# Discuss with reviewers (auto-continues current session)
council discuss "Can you elaborate on the first issue?"

# Continue a review conversation (explicit session ID)
council continue <session-id> "Here's more context about X..."

# List all sessions or show specific session details
council status
council status <session-id>

# Clean up old sessions (default: 7 days)
council cleanup
council cleanup 30

# Show help
council help
council --help

As a Skill (Claude Code or OpenCode)

Once setup is complete, invoke the skill directly:

• /council - Review the most recent plan from ~/.claude/plans/
• /council ~/my-plan.md - Review a specific file

The assistant will:

1. Run the review
2. Parse the JSON output (including round number)
3. Evaluate each piece of feedback - accept valid issues, reject already-addressed ones
4. Revise the plan if needed
5. Run another round if models haven't approved
6. Continue until consensus or max rounds reached
7. Present final plan to user for approval

Iterative Refinement

Council supports multi-round review with automatic session continuation:

How It Works

1. Round 1: Assistant calls council review plan.md - creates new session
2. Evaluate: Assistant reads feedback, accepts/rejects each issue
3. Revise: Assistant updates plan based on accepted feedback
4. Round 2: Assistant calls council review plan.md again - auto-continues session
5. Repeat: Continue until all models approve (consensus)

Anti-Laziness Check

If models approve too quickly (before round 3) with vague feedback like "looks good", use:

council review --press plan.md

This sends a special prompt requiring models to:

1. List specific sections they reviewed
2. Explain why the plan is ready
3. Identify any remaining concerns

Session Auto-Continuation

Council automatically tracks sessions based on the parent tool:

• Claude Code: Uses CLAUDE_SESSION_ID (set by hook)
• OpenCode: Uses OPENCODE_SESSION_ID (set by plugin)

When either is set, council review automatically:

• Finds the existing council session for this parent session
• Continues the OpenCode conversations with full context
• Increments the round number

Models can see their previous critique and verify if issues were addressed.

Configuration

Edit council.config.toml to customize:

[agents.gemini-3-pro]
start = "opencode run -m opencode/gemini-3-pro --format json"
continue = "opencode run --format json"
flags = ""

[agents.gpt-5-2]
start = "opencode run -m opencode/gpt-5.2 --format json"
continue = "opencode run --format json"
flags = ""

[settings]
timeout = 300
sessionDir = "~/.council/sessions"
plansDir = "~/.claude/plans"
maxRounds = 10
antiLazinessRound = 3

reviewPrompt = """
## TASK
Review this implementation plan...
"""

[pressPrompt]
template = """
You previously indicated this plan has no major issues.

**Before confirming, you MUST:**
1. List at least 3 specific sections you reviewed
2. Explain WHY this plan is ready
3. Identify ANY remaining concerns

{{PLAN_CONTENT}}
"""

Configuration Options

Setting	Description	Default
timeout	Seconds before timing out	300
sessionDir	Where to store session files	~/.council/sessions
plansDir	Where to look for plan files	~/.claude/plans
maxRounds	Maximum review rounds before stopping	10
antiLazinessRound	Use press prompt if consensus before this round	3

JSON Output Format

Review Output (stdout)

{
  "sessionId": "session-1704067200000-a1b2c3d4e5f6",
  "file": "/path/to/plan.md",
  "round": 1,
  "results": {
    "gemini-3-pro": "### Verdict: NEEDS REVISION\n\n### Critical Issues...",
    "gpt-5-2": "### Verdict: APPROVE\n\n..."
  },
  "errors": {
    "gemini-3-pro": "Command timed out after 300s"
  }
}

• round: Current round number (starts at 1)
• results: Contains the output from each successful reviewer
• errors: Only present if errors occurred
• Progress messages go to stderr

Status Output

{
  "sessions": [
    {
      "id": "session-1704067200000-a1b2c3d4e5f6",
      "file": "/path/to/plan.md",
      "startedAt": "2024-01-01T00:00:00.000Z",
      "agents": ["gemini-3-pro", "gpt-5-2"]
    }
  ]
}

Session Management

Sessions are stored in ~/.council/sessions/ as JSON files. Each session contains:

• The current plan content
• Each reviewer's output and OpenCode session IDs
• Round history (plan content and outputs per round)
• Timestamps

Session IDs follow the pattern: session-<timestamp>-<nanoid> (e.g., session-1704067200000-a1b2c3d4e5f6)

Automatic Session Mapping

Council automatically maps parent sessions to council sessions:

• Claude Code: Maps CLAUDE_SESSION_ID → council session
• OpenCode: Maps OPENCODE_SESSION_ID → council session
• Session mappings are stored in ~/.council/session-map.json

When you run council review or council discuss, it automatically continues the same session. Multiple parent sessions can work on different plans simultaneously.

Note: If both CLAUDE_SESSION_ID and OPENCODE_SESSION_ID are set, Council prefers CLAUDE_SESSION_ID and logs a warning.

Environment Variables

Variable	Description
COUNCIL_DEBUG=1	Show stack traces in error output
CLAUDE_SESSION_ID	Set by Claude Code hook - enables auto-continuation
OPENCODE_SESSION_ID	Set by OpenCode plugin - enables auto-continuation
NO_COLOR=1	Disable colored output

CLI Flags

Flag	Description
-h, --help	Show help message
-v, --version	Show version
-d, --debug	Show stack traces in errors
--press	Use anti-laziness prompt (review command)

Setup Flags

Flag	Description
--claude	Install for Claude Code only
--opencode	Install for OpenCode only
--both	Install for both tools

Review Prompt

Council uses a structured 7-section prompt:

1. TASK: What the reviewer should do
2. EXPECTED OUTCOME: Structure of the assessment
3. CONTEXT: The plan content (injected)
4. CONSTRAINTS: Focus areas
5. MUST DO: Evaluation criteria
6. MUST NOT DO: Things to avoid
7. OUTPUT FORMAT: Verdict and issue structure

Reviewers return verdicts: APPROVE, NEEDS REVISION, or REJECT

Critical Design Principle

The reviewing models are peers giving feedback, not blocking reviewers. The assistant:

• Uses its own judgment on their comments
• Accepts valid issues that improve the plan
• Rejects feedback that's already addressed or not applicable
• Discusses rejections with models before declaring consensus

Council provides diverse perspectives; the assistant decides what's valid and actionable.

Example Workflow

Single Round

1. User enters plan mode in their AI assistant
2. Assistant writes a plan to ~/.claude/plans/
3. User: /council
4. Assistant runs council review and parses the JSON
5. Assistant presents synthesis and recommendations

Iterative Refinement

1. Round 1: Assistant reviews plan
   • Gemini: "Missing error handling" (valid - accept)
   • GPT: "Add rate limiting" (not needed - reject)
2. Assistant revises plan with error handling
3. Assistant uses council discuss to explain rate limiting rejection
4. Round 2: Assistant reviews again
   • Gemini: "Error handling looks good. Approved."
   • GPT: "Understood about rate limiting. Approved."
5. Consensus reached - Assistant presents final plan to user
6. User approves - Assistant creates GitHub issue and begins implementation

Development

# Install dependencies
bun install

# Type check
bun run typecheck

# Run tests
bun test

# Link for local development
bun link

# Debug mode
COUNCIL_DEBUG=1 council review
council --debug review

Requirements

• Bun >= 1.0.0 (runtime)
• OpenCode CLI (for model access)

License

MIT