Documentation
Everything you need to get started with Cohort.
Installation
Cohort's core library has zero dependencies -- just the Python standard library. Install extras only for the features you need. Requires Python 3.11+.
# Recommended — full server + MCP tools pip install "cohort[server]" # Library only (httpx + fastmcp, no server) pip install cohort # Everything including dev tools pip install "cohort[all]"
Quick Start
Create a channel, define agents, start a session, and let the orchestrator pick who speaks next. This is the complete working example -- 10 lines to your first multi-agent meeting.
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 agents agents = { "architect": {"triggers": ["api", "design"], "capabilities": ["backend architecture"]}, "tester": {"triggers": ["testing", "qa"], "capabilities": ["test strategy"]}, } # 3. Start orchestrator session orch = Orchestrator(chat, agents=agents) session = orch.start_session("design-review", "REST API design review", list(agents)) # 4. Get next speaker recommendation rec = orch.get_next_speaker(session.session_id) print(f"Next: {rec['recommended_speaker']} - {rec['reason']}") # 5. Record a turn (agent spoke) orch.record_turn(session.session_id, "architect", "msg-001")
No HTTP server required. The orchestrator works directly with file-backed storage. Add cohort[mcp] when you want MCP integration.
Agent Development
Agents are duck-typed. Any object with name, role, capabilities, relevance_score(), and can_contribute() satisfies the protocol. No base class, no imports, no vendor SDK.
@runtime_checkable class AgentProfile(Protocol): """Any object with these attributes works.""" name: str role: str capabilities: list[str] def relevance_score(self, topic: str) -> float: ... def can_contribute(self, context: dict) -> bool: ...
For most use cases, define agents as simple JSON. Cohort's built-in AgentConfig handles scoring automatically.
{
"architect": {
"triggers": ["api", "design", "architecture"],
"capabilities": ["REST API design", "system design"],
"complementary_agents": ["developer", "tester"],
"phase_roles": {
"DISCOVER": "high",
"PLAN": "high",
"EXECUTE": "low"
}
}
}
The orchestrator scores agents across 5 dimensions to pick the next speaker:
Agents progress through stakeholder statuses (active -> approved_silent -> observer -> dormant) as their contribution threshold rises. Topic shifts re-engage dormant agents whose expertise becomes relevant again.
API Reference
Start the server with python -m cohort serve --port 5100. All endpoints return JSON.
# Request { "channel": "design-review", "sender": "architect", "message": "We need cursor-based pagination @developer", "response_mode": "smarter" // smart | smarter | smartest } # Response {"success": true, "message_id": "a1b2c3d4..."}
MCP Integration -- Use Cohort from any MCP-compatible client:
# Start MCP server python -m cohort.mcp.server # Available MCP tools: read_channel # Fetch messages (read-only) post_message # Post to channel list_channels # List channels (read-only) create_channel # Create new channel channel_summary # Compact activity summary (read-only) condense_channel # Archive + summarize old messages
Storage Backends
Storage is protocol-based. Cohort ships two backends; implement the interface to bring your own (Postgres, Redis, SQLite, etc.).
class StorageBackend(Protocol): def save_message(self, channel: str, message: dict) -> str: ... def get_messages(self, channel: str, limit: int = 50) -> list[dict]: ... def save_channel(self, channel_id: str, metadata: dict) -> None: ... def get_channel(self, channel_id: str) -> dict | None: ... def list_channels(self) -> list[dict]: ... def delete_channel(self, channel_id: str) -> bool: ... def restore_channel(self, channel_id: str) -> bool: ...
messages.json, channels in channels.json. Soft-delete with 30-day trash retention.CLI Reference
185 commands across 61 categories. Most work without a server (file-backed storage). Every command supports --json for scripting.
# List all agents, grouped by type python -m cohort agents list --verbose # Show full agent detail (skills, partnerships, pitfalls) python -m cohort agent python_developer python -m cohort agent python_developer --prompt # full system prompt # Find the best agent for a task python -m cohort route "fix auth bug in the API" --json # Show agent partnership graph python -m cohort graph # Create a new agent from scratch python -m cohort agents create --name "Data Analyst" --role "Analyzes data" --type specialist
# List channels, read messages, search python -m cohort channels list python -m cohort channel read code-review --limit 20 python -m cohort channel search "authentication" python -m cohort channel post general "Deploying v2.1"
# Full queue lifecycle python -m cohort queue add "Fix auth regression" -p high -a python_developer python -m cohort queue claim python -m cohort queue complete a1b2c3d4 --result "Fixed in abc123" # Recurring schedules python -m cohort schedule create -a qa_agent -d "Run tests" -t interval -e 3600
# System dashboard, diagnostics, hardware python -m cohort status python -m cohort doctor python -m cohort hardware # Manage API keys (20 providers, encoded at rest) python -m cohort secret providers python -m cohort secret set service:anthropic sk-ant-... python -m cohort secret set service:aws AKIA... --extra '{"secret_access_key": "...", "region": "us-east-1"}' # Search, web fetch, YouTube transcripts python -m cohort search "python best practices" python -m cohort web fetch https://example.com python -m cohort youtube transcript dQw4w9WgXcQ
See full CLI reference for all 185 commands with examples and flag documentation.
Ready to Build?
Install Cohort and have your first multi-agent discussion running in under five minutes.