# Cohort

**[Quickstart](QUICKSTART.md)** | **[Website](https://rwheeler007.github.io/cohort/)** | **[Docs](https://rwheeler007.github.io/cohort/docs.html)** | **[Benchmarks](https://rwheeler007.github.io/cohort/benchmarks.html)** | **[Discord](https://discord.gg/cohort)** | **[Twitter](https://twitter.com/cohort_dev)**

Multi-agent orchestration with loop prevention, contribution scoring, and MCP integration.

Cohort manages structured discussions between AI agents. It decides **who speaks next**, prevents conversational loops, and scores contributions across five dimensions -- so your agents stay productive instead of talking in circles.

## Why Cohort?

Every multi-agent framework lets agents talk. Cohort decides **who should talk, when they should stop, and whether what they said was worth hearing.**

| | Cohort | CrewAI | LangGraph |
| --- | --- | --- | --- |
| **Core deps** | 0 | 25+ | 30+ (transitive) |
| **Default inference** | Local (Ollama / llama.cpp) | Cloud (OpenAI) | Cloud (varies) |
| **API key required** | No (local) / optional (cloud) | Yes | Yes |
| **Contribution scoring** | 5-dimension engine | -- | -- |
| **Loop prevention** | Architectural (recency + novelty + gating) | Max iterations (timeout) | Conditional edges (manual) |
| **Data leaves your machine** | Your choice (local default) | Yes + telemetry | Optional |
| **MCP integration** | Built-in (lite + full modes) | -- | -- |
| **Cost** | $0 local | API + $99-$10K Enterprise | API + $39/seat Platform |

**Zero dependencies.** `pip install cohort` pulls nothing. Your agents, your hardware, your data.

**Extracted from production.** These patterns weren't designed from theory -- they were extracted from a system running 60+ agents, then packaged clean with 1,100+ tests.

## Claude Code Channels Integration

Cohort was the first third-party integration with [Claude Code Channels](https://docs.anthropic.com/en/docs/claude-code/channels) -- Anthropic's protocol for persistent, event-driven agent sessions.

```
03:00 AM MT  --  Anthropic ships Claude Code Channels (research preview)
06:03 AM MT  --  Cohort integration committed. Agent pipeline operational.
06:45 AM MT  --  Working checkpoint. CLI module, agent enrichment, context hydration.
07:11 AM MT  --  First multi-round agent roundtable via Channels.
```

Channels give Cohort agents persistent sessions with automatic context hydration, idle reaping, and priority-based eviction. Agents respond to events -- CI results, chat messages, monitoring alerts -- even when you're not at the terminal.

This is what Cohort is built for: when a new protocol drops, the orchestration layer is already there. You just plug it in.

## What It Looks Like

Four agents discussing an API redesign. Cohort scores each agent across five dimensions and decides who should speak:

```
  architect           | Let's investigate the existing /users endpoint before we
                      | redesign it. We need to research what similar APIs do.

  -- Who should speak? --
    Rank  Agent                  Score   Phase
    ----  --------------------   -----   --------
    1.    researcher             0.23    DISCOVER  ####
    2.    architect              0.19    DISCOVER  ###
    3.    developer              0.17    DISCOVER  ###
    4.    tester                 0.17    DISCOVER  ###

  -- Gating each agent --
    gate(researcher          ) -> SPEAK   score=0.61  threshold=0.30
    gate(developer           ) -> SPEAK   score=0.55  threshold=0.30
    gate(tester              ) -> SPEAK   score=0.55  threshold=0.30
```

Researcher ranks highest because the topic matches their triggers. Later, when the conversation shifts to implementation, the developer gets promoted. When a security issue surfaces during testing, the researcher re-engages automatically.

Run it yourself: `python examples/design_review_demo.py`

## Features

- **Zero dependencies** -- `pip install cohort` pulls nothing
- **MCP integration** -- LLM tools for channels, agents, search, checklists (works standalone or with server)
- **Contribution scoring** -- 5-dimension relevance matrix (novelty, expertise, ownership, phase alignment, data ownership)
- **Loop prevention** -- Stakeholder gating keeps agents from repeating each other
- **Topic shift detection** -- Automatically re-engages relevant agents when the conversation changes direction
- **Local LLM** -- Hardware detection, Ollama/llama.cpp integration, setup wizard
- **Protocol-first design** -- `AgentProfile` and `StorageBackend` are `@runtime_checkable` protocols. Bring your own agents and storage.

## Install

```bash
pip install cohort              # zero-dep core — file storage, CLI, scoring engine
pip install cohort[lite]        # same as above, explicit lite path (file-based MCP simulation)
pip install cohort[mcp]         # adds MCP server for any client (Cursor, Windsurf, etc.)
pip install cohort[claude]      # recommended — full Claude Code experience + setup wizard
pip install cohort[all]         # everything including dev tools
```

Requires Python 3.11+.

## Using an MCP Client? Just Say "Get Started"

If you use an MCP-compatible client (Claude Code, Cursor, Windsurf, etc.), Cohort includes a built-in interactive walkthrough. Clone the repo, connect via MCP, and say **"get started"** -- the LLM will walk you through creating channels, registering agents, and seeing the scoring engine in action, step by step, using real tools. No docs reading required.

The walkthrough is powered by `CLAUDE.md` at the repo root -- it pre-loads the LLM with full knowledge of Cohort's API, architecture, and conventions. It's the fastest way to go from zero to a working multi-agent setup.

## MCP Integration

Cohort includes a built-in MCP server with two operating modes:

**Lite mode** (standalone, no server required):
```json
{
  "mcpServers": {
    "cohort": {
      "command": "cohort",
      "args": ["mcp"],
      "env": {
        "COHORT_DATA_DIR": "/path/to/your/data"
      }
    }
  }
}
```

Or add a local LLM server (Ollama) alongside it:
```json
{
  "mcpServers": {
    "cohort": {
      "command": "cohort",
      "args": ["mcp"],
      "env": { "COHORT_DATA_DIR": "/path/to/your/data" }
    },
    "cohort-local-llm": {
      "command": "cohort",
      "args": ["mcp-local"]
    }
  }
}
```

Lite mode operates directly on file-based storage. Channels, messages, agent profiles, checklists, and search all work without any server process.

**Full mode** (auto-detected when Cohort server is running):

If a Cohort server is running on `localhost:5100`, the MCP server automatically upgrades to full mode with live agent routing, real-time sessions, work queue, and briefing generation.

### Available MCP Tools

| Tool | `[mcp]` | `[claude]` | Description |
|------|---------|------------|-------------|
| `read_channel` | Yes | Yes | Read messages from a channel |
| `post_message` | Yes | Yes | Post a message to a channel |
| `list_channels` | Yes | Yes | List all channels |
| `cohort_create_channel` | Yes | Yes | Create a new channel |
| `channel_summary` | Yes | Yes | Compact activity summary |
| `cohort_list_agents` | Yes | Yes | List all agents |
| `cohort_get_agent` | Yes | Yes | Get agent details |
| `cohort_get_agent_memory` | Yes | Yes | View agent memory |
| `cohort_add_fact` | Yes | Yes | Add a learned fact |
| `cohort_clean_memory` | Yes | Yes | Trim working memory |
| `cohort_search_messages` | Yes | Yes | Search across channels |
| `get_checklist` | Yes | Yes | Read to-do checklist |
| `update_checklist` | Yes | Yes | Add/complete/remove tasks |
| `condense_channel` | -- | Yes | LLM-powered channel summarisation |
| `cohort_create_agent` | -- | Yes | Create a new agent |
| `cohort_discussion` | -- | Yes | Live multi-agent discussion (server required) |
| `cohort_compiled_discussion` | -- | Yes | Single-call multi-agent discussion (local Ollama) |
| `cohort_adopt_persona` | -- | Yes | Adopt an agent's persona for the conversation |

## Quick Start (Python API)

```python
from cohort import JsonFileStorage, Orchestrator
from cohort.chat import ChatManager

# 1. Set up storage and chat
chat = ChatManager(JsonFileStorage("my_data"))
chat.create_channel("design-review", "API design review")

# 2. Define your agents (triggers and capabilities drive scoring)
agents = {
    "architect": {"triggers": ["api", "design"], "capabilities": ["backend architecture"]},
    "tester":    {"triggers": ["testing", "qa"], "capabilities": ["test strategy"]},
}

# 3. Post a message and start a session
chat.post_message("design-review", sender="user", content="Review the REST API design")
orch = Orchestrator(chat, agents=agents)
session = orch.start_session("design-review", "REST API design review", initial_agents=list(agents))

# 4. Ask who should speak next
rec = orch.get_next_speaker(session.session_id)
print(f"Next speaker: {rec['recommended_speaker']}")
print(f"Reason: {rec['reason']}")

# 5. Record turns and let Cohort manage the flow
orch.record_turn(session.session_id, "architect", "msg-001")
```

## CLI

Cohort has two interfaces that share the same channels, agents, and scoring engine:

- **MCP mode** -- your LLM client (Claude Code, Cursor, etc.) talks to Cohort through MCP tools. Run `cohort setup` to configure, restart your client, and say **"get started"**.
- **CLI mode** -- run commands directly from the terminal. Useful for scripting, CI, or working without an LLM client.

Both modes read and write the same data. Work done in one shows up in the other.

```bash
# Channel operations
cohort say --sender architect --channel review --file conv.jsonl \
    --message "We should use pagination for the list endpoint"
cohort read review                          # Read channel history
cohort read review --limit 50               # Read more messages
cohort search "database schema"             # Search across all channels

# Scoring engine
cohort gate --agent tester --channel review --file conv.jsonl \
    --agents agents.json --format json
cohort next-speaker --channel review --file conv.jsonl \
    --agents agents.json --top 3

# Multi-agent discussions
cohort discuss --agents backend_dev,qa_engineer --channel review \
    --prompt "Design the API"
cohort roundtable --agents backend_dev,qa_engineer \
    --topic "Connection pooling" --channel review

# Briefings and setup
cohort briefing generate --hours 24
cohort setup                                # Interactive setup wizard
cohort tutorial                             # Scoring engine walkthrough

# MCP servers
cohort mcp                                  # For Claude Code, Cursor, etc.
cohort mcp-local                            # Local Ollama server
```

## Architecture

```
                    +-----------------+
                    |  Orchestrator   |  Session management, turn control
                    +--------+--------+
                             |
              +--------------+--------------+
              |                             |
     +--------+--------+          +--------+--------+
     |   ChatManager    |          |    Meeting      |
     | channels, messages|          | scoring, gating |
     +--------+--------+          +-----------------+
              |
     +--------+--------+
     | StorageBackend   |  (Protocol -- bring your own)
     |  JsonFileStorage |  (default: flat-file JSON)
     |  SqliteStorage   |  (optional: SQLite)
     +-----------------+
```

**Orchestrator** manages sessions: who's invited, whose turn it is, when the topic shifts.

**Meeting** scores each agent across five dimensions before allowing them to speak:

| Dimension | Weight | What it measures |
|-----------|--------|-----------------|
| Domain expertise | 30% | Keyword overlap between topic and agent triggers/capabilities |
| Complementary value | 25% | Are this agent's partners active? |
| Historical success | 20% | Past performance on similar topics |
| Phase alignment | 15% | Is this the right agent for the current workflow phase? |
| Data ownership | 10% | Does this agent own data relevant to the topic? |

Agents move through stakeholder statuses: **active** -> **approved_silent** -> **observer** -> **dormant**. Each status raises the threshold to speak, preventing agents from dominating.

## Local LLM Integration

Cohort includes built-in support for local inference:

```bash
cohort setup  # Interactive wizard: detects GPU, installs Ollama, picks model
```

- **Hardware detection** -- Identifies GPU VRAM and recommends appropriate models
- **Ollama client** -- Direct integration for local inference
- **llama.cpp support** -- For direct GGUF model serving
- **Model routing** -- Automatic model selection based on task complexity

## Protocols

Cohort uses Python protocols -- no base classes required:

```python
from cohort import AgentProfile, StorageBackend

class MyAgent:
    name: str = "custom"
    role: str = "specialist"
    capabilities: list[str] = ["custom-domain"]

    def relevance_score(self, topic: str) -> float:
        return 0.8 if "custom" in topic else 0.2

    def can_contribute(self, context: dict) -> bool:
        return True

assert isinstance(MyAgent(), AgentProfile)  # True -- duck typing
```

## Examples

| Example | What it shows |
|---------|---------------|
| `examples/quick_cohort.py` | Minimal Python API -- 2 agents, session, speaker recommendation |
| `examples/scored_discussion.py` | Score breakdowns, gating, recency, topic shift (Python + CLI) |
| `examples/design_review_demo.py` | Full 4-agent design review with phase transitions (CLI) |
| `examples/file_collaboration.sh` | Bash-only collaboration -- any language can participate |

## Personas

Cohort includes sample persona files (~25 lines, <500 tokens each) that demonstrate the format:

```python
from cohort.personas import load_persona

persona = load_persona("analytics_agent")  # Returns markdown text or None
```

These are **format examples** for writing your own. Use them as templates to build agents tailored to your domain.

## Development

```bash
git clone https://github.com/rwheeler007/cohort.git
cd cohort
pip install -e ".[dev]"
pytest
ruff check cohort/ tests/
mypy cohort/
```

## License

Apache 2.0 -- see [LICENSE](LICENSE) for details.
