CLI

185 commands across 61 categories. Agents, channels, work queues, meeting control, models, benchmarks, learning, analysis, cloud providers, assessments, ecosystem inventory, session management, and more -- all from the terminal.

Everything runs via python -m cohort <command>

Commands

Command Categories

agents / agent
list, show, create, prompt channels / channel
list, read, create, post, search, archive queue
list, add, claim, complete, fail, cancel tasks / task
list, show, schedules health / status / doctor
system diagnostics, hardware briefing / intel
reports, RSS feeds, articles route / graph
agent matching, partnerships memory / teach
facts, stats, clean search / web / youtube
DuckDuckGo, fetch, transcripts model
list, pull, tier, budget, recommend benchmark
scenarios, runs, show, delete learn
profile, bootstrap, status analyze
keywords, overlap, score, distill meet
18 cmds: sessions, gating, scoring, phase secret / profile / tools / config
20 providers, permissions, merged config serve / setup / codegen
server, wizard, LLM codegen service
manage, status, logs cloud
providers, test, budget context
inspect prompt context import
preferences from other tools assess
agent assessment results hydrate
seed channels with content quiz
import assessment questions inject
test fact injection overnight
runner status, history inventory
list, search, sources, refresh sessions
status, show, reap, purge

Agents

cohort agents listFree

List all agents, grouped by type (specialist, orchestrator, supervisor, infrastructure). Shows agent ID, role, and active status.

$ python -m cohort agents list --verbose

SPECIALIST (18)

--------------------------------------------------

[*] python_developer Senior Python Software Engineer

[*] security_agent Code & Infrastructure Security Engineer

--verbose, -v: Show capabilities for each agent
--all: Include hidden agents
--json: Output as JSON (pipe to jq)

cohort agent <name>Free

Show full details for a single agent: role, personality, capabilities, domain expertise, skill levels, partnerships, and common pitfalls.

$ python -m cohort agent python_developer

Skill Levels:

[#########.] 9/10 python_backend

[#########.] 9/10 api_design

[########..] 8/10 async_programming

--prompt: Show the full system prompt (markdown)
--json: Output as JSON

cohort agents createFree

Scaffold a new agent with config, prompt, and memory files. Generates a complete agent directory ready for use.

$ python -m cohort agents create --name "Data Analyst" --role "Analyzes data patterns" \

--type specialist --capabilities "SQL,visualization,pandas"

[OK] Created agent: data_analyst

Channels

cohort channels listFree

List all channels with member count and description. File-backed -- no server required.

$ python -m cohort channels list

#code-review 5 members Architecture discussions

#daily-standup 8 members Morning sync

--all: Include archived channels

cohort channelFree

Channel operations: read messages, create channels, post messages, search across channels, and archive old channels.

read create post search archive

# Read the last 20 messages

$ python -m cohort channel read code-review --limit 20

# Search across all channels

$ python -m cohort channel search "authentication" --json

# Post a message

$ python -m cohort channel post general "Deploying v2.1 now" --sender user

Work Queue

cohort queueFree

Full work queue lifecycle. File-backed FIFO with priority ordering. Add tasks, claim them for processing, mark as completed or failed, and cancel. No server required.

list show add active claim complete fail cancel

# Add a high-priority task

$ python -m cohort queue add "Fix auth regression" -p high -a python_developer

[OK] Queued: a1b2c3d4 (high) Fix auth regression

# Claim the next item

$ python -m cohort queue claim

# Mark it done

$ python -m cohort queue complete a1b2c3d4 --result "Fixed in commit abc123"

Tasks & Scheduling

cohort tasks / cohort taskFree

List task instances and view details. Tasks are created by the scheduler or work queue and tracked through their lifecycle (briefing, executing, completed, failed).

$ python -m cohort tasks list --status executing

$ python -m cohort task a1b2c3d4 --json

cohort scheduleFree

Manage recurring task schedules. Create cron-based or interval schedules, toggle them on/off, and delete them. Supports up to 50 active schedules with a 5-minute minimum interval.

list show create toggle delete

$ python -m cohort schedule create -a qa_agent -d "Run unit tests" -t interval -e 3600

[OK] Created schedule: a1b2c3d4

interval 3600 -> qa_agent

System & Diagnostics

cohort statusFree

Single-command system dashboard. Shows server status, Ollama connectivity, agent count, channel count, and queue depth.

$ python -m cohort status

Server: [OK] running on :5100

Ollama: [OK] reachable (12 models)

Agents: 23 total, 23 active

Channels: 5

Queue: 2 queued, 1 active

cohort doctorFree

Run 6 diagnostic checks: Python version, agents directory, data dir writable, Ollama reachable, server running, and Git available. Fix issues before they become problems.

$ python -m cohort doctor

[OK] Python >= 3.10 -- 3.13.2

[OK] Agents directory -- 23 configs found

[OK] Ollama reachable -- 12 models available

cohort hardwareFree

Detect GPUs, VRAM, and platform info. Shows per-GPU VRAM usage bars so you know exactly what's available for inference.

$ python -m cohort hardware

GPUs (2):

[0] NVIDIA GeForce RTX 3080

VRAM: [##########..........] 6,400MB / 12,288MB (52% used)

cohort healthFree

Check registered service health. Quick pass/fail for each service endpoint.

Intelligence & Briefings

cohort briefingOllama

Generate or view executive briefings. Summarizes channel activity, task progress, and blockers over a configurable time window.

$ python -m cohort briefing generate --hours 24

$ python -m cohort briefing latest --format json

cohort briefingsFree

Browse past briefing reports. List recent briefings with dates and time ranges, or find the latest HTML report.

list html

$ python -m cohort briefings list --limit 5

2026-03-10T20:14 2026-03-09 to 2026-03-10 id: briefing

2026-03-10T19:52 2026-03-09 to 2026-03-10 id: briefing

cohort intelFree

RSS feed ingestion and article browsing. Fetch feeds manually, browse top-scored articles, or see recent articles sorted by date.

fetch top recent

$ python -m cohort intel top --limit 10 --min-score 7

[##########] 10 Building LLM-powered CLI tools

Hacker News (best) 2026-03-10

Agent Routing

cohort routeFree

Find the best agent for a task. Scores all agents by trigger match, capability overlap, and domain expertise. Returns ranked results with match percentages.

$ python -m cohort route "fix authentication bug in the API"

1. [########............] 41% python_developer

Senior Python Software Engineer

2. [#####...............] 25% security_agent

--type: Prefer a specific agent type (specialist, orchestrator, etc.)
--limit: Max results (default: 5)

cohort graphFree

Visualize the full agent partnership graph. Shows who collaborates with whom and the nature of each partnership (security review, test strategy, API contracts).

$ python -m cohort graph

python_developer

-> security_agent (Security reviewer for all code changes)

-> qa_agent (Test strategy partner)

-> javascript_developer (API contract peer)

cohort partnershipsFree

Show required consultations for a specific agent before task execution (security reviews, QA sign-offs, architecture checks).

$ python -m cohort partnerships python_developer --task "build REST API"

Agent Memory

cohort memoryFree

View an agent's learned facts, memory statistics, or trim working memory. Learned facts are never deleted -- only working memory is trimmed.

facts stats clean

$ python -m cohort memory python_developer stats

Learned facts: 12

Working memory: 54

$ python -m cohort memory python_developer clean --keep 10 --dry-run

[DRY RUN] Working memory removed: 44, kept: 10

cohort teachFree

Add a learned fact to an agent's memory. Facts persist across sessions and inform the agent's future responses.

$ python -m cohort teach python_developer "Always use connection pooling for concurrent DB access" -c high

[OK] Taught python_developer: Always use connection pooling...

Search & Web

cohort searchFree

Search the web via DuckDuckGo. No API key required. Falls back to Google Custom Search, SerpAPI, or Serper if configured.

$ python -m cohort search "python CLI best practices" -n 5

cohort web fetchFree

Fetch a URL and extract readable text (HTML tags stripped). Useful for piping web content into other tools.

$ python -m cohort web fetch https://example.com --limit 500

--raw: Show raw HTML instead of extracted text
--limit: Max characters (default: 2000)

cohort youtubeFree*

YouTube tools. Transcript extraction is free (no API key). Video search requires a Google API key.

transcript languages search

# Free -- no API key needed

$ python -m cohort youtube transcript dQw4w9WgXcQ --language en

# Requires Google API key

$ python -m cohort youtube search "pytorch tutorials" -n 10

* Transcript extraction uses youtube-transcript-api (pip install youtube-transcript-api). Does not consume YouTube API quota.

Model Management

cohort modelFree

Full Ollama model management. List installed models, pull new ones, remove old ones, configure response tier assignments, set token budget limits, and get VRAM-based model recommendations.

list pull remove tier budget recommend

# List installed models

$ python -m cohort model list

# Show Smart/Smarter/Smartest tier assignments

$ python -m cohort model tier

# Change a tier's model

$ python -m cohort model tier set smartest qwen3.5:35b-a3b

# Set daily token budget for cloud API

$ python -m cohort model budget set --daily 1000000

# Auto-detect VRAM and recommend best model

$ python -m cohort model recommend

Benchmarking

cohort benchmarkFree

A/B benchmark runner. List scenarios, browse historical runs with scores, inspect individual run details, and manage results. Persisted to SQLite.

scenarios runs show delete

$ python -m cohort benchmark scenarios

code_review Code Review: Subtle Bug Detection

architecture Architecture: Caching Layer Design

triage Bug Triage: Priority Classification

$ python -m cohort benchmark runs --limit 5

Learning & Profile

cohort learnFree

Conversation learning system. View and create user profiles that adapt agent behavior, check learning system status, and manage extraction configuration.

profile bootstrap status

# Create a user profile

$ python -m cohort learn bootstrap --name "Ryan" --role "Engineer"

# View current profile

$ python -m cohort learn profile

# Check learning system config

$ python -m cohort learn status

Text Analysis

cohort analyzeFree*

Text analysis toolkit. Extract keywords, measure semantic overlap between texts, score articles against project strategy, and distill verbose text to structured briefings.

keywords overlap score distill

$ python -m cohort analyze keywords "async database connection pooling"

1. async

2. database

3. connection

4. pooling

$ python -m cohort analyze overlap "Python database pooling" "JavaScript database connections"

Score: [######..............] 33.3%

Shared: database

* keywords, overlap, and score are free. distill requires Ollama.

Meeting & Stakeholders

cohort meetFree

18-command meeting control surface. Stakeholder identification, session lifecycle, participant management, scoring introspection, phase detection, and standalone meeting mode. The primary consumers are orchestrating agents and skills that need to control multi-agent discussion dynamics programmatically.

stakeholders relevance start stop pause resume status extend promote demote add remove next score phase context enable disable

# Offline: find stakeholders and score relevance (no server needed)

$ python -m cohort meet stakeholders "security audit" --threshold 0.01

1. [#########......] 60.2% security_agent

2. [####...........] 28.1% python_developer

$ python -m cohort meet relevance security_agent "authentication module audit"

# Start a meeting session with auto-selected agents

$ python -m cohort meet start my-channel "API redesign" --agents ceo,pd,sec --turns 15

[OK] Session started: s_20260325_143500_abc123

# Check session status (accepts session ID or channel name)

$ python -m cohort meet status my-channel

Session: s_20260325_143500_abc123

Channel: #my-channel State: ACTIVE Phase: PLAN

Turn: 8 / 15

ACTIVE (2): python_developer, security_agent

SILENT (1): ceo

# Promote/demote agents mid-discussion

$ python -m cohort meet promote s_20260325_143500_abc123 ceo

[OK] ceo -> ACTIVE

$ python -m cohort meet demote s_20260325_143500_abc123 security_agent --to observer

[OK] security_agent -> OBSERVER

# Scoring: who should speak next, full relevance breakdown

$ python -m cohort meet next s_20260325_143500_abc123

Recommended: python_developer Score: 0.782 Phase: PLAN

$ python -m cohort meet score s_20260325_143500_abc123 python_developer

[###########....] 73.2% domain_expertise

[########.......] 55.0% phase_alignment

# Detect discussion phase from message content

$ python -m cohort meet phase my-channel

Phase: EXECUTE

# Lightweight meeting mode (no session, just stakeholder gating)

$ python -m cohort meet enable my-channel --agents pd,sec,co --topic "auth rewrite"

[OK] Meeting mode enabled on #my-channel

$ python -m cohort meet disable my-channel

--json: Machine-readable JSON output (all subcommands)
--threshold <float>: Minimum relevance score for stakeholders (default: 0.15)
--agents <a,b,c>: Comma-separated agent IDs (start, enable)
--turns <int>: Max turns for session (start: 20, extend: 10)
--to <silent|observer|dormant>: Target status for demote (default: silent)
--topic <text>: Optional topic for keyword scoring (enable)

Configuration & Secrets

cohort secretFree

Manage API keys for 20 providers. Keys are XOR-encoded at rest. Multi-field credentials (AWS access key + secret, Twitter key + bearer token) supported via --extra JSON.

list set remove providers

# See all 20 supported providers and their fields

$ python -m cohort secret providers

# Set a simple API key

$ python -m cohort secret set service:anthropic sk-ant-...

# Set multi-field credentials

$ python -m cohort secret set service:aws AKIA... --extra '{"secret_access_key": "...", "region": "us-east-1"}'

cohort profileFree

Manage your user profile. Set your name, avatar, role, and other fields that get injected into agent context.

show set

$ python -m cohort profile set name "Ryan Wheeler"

$ python -m cohort profile set role "Senior Engineer"

cohort config showFree

Single-command view of all configuration: response tiers, token budgets, task temperatures, response modes, secrets count, and Ollama status.

$ python -m cohort config show

[S] Smart: qwen3.5:9b (fallback: none)

[S+] Smarter: qwen3.5:9b (fallback: smart)

[S++] Smartest: qwen3.5:35b-a3b (fallback: cloud_api)

cohort tools permissionsFree

Inspect tool permissions for agents. Shows which tools each agent can access, their permission profile, and MCP server count.

$ python -m cohort tools permissions

python_developer [developer_safe] Read, Write, Edit, Glob, Grep

security_agent [readonly ] Read, Glob, Grep

Infrastructure

cohort serveFree

Start the HTTP server with the web dashboard. Required for real-time features (Socket.IO, @mention routing). Most CLI commands work without it.

$ python -m cohort serve --host 0.0.0.0 --port 5100

cohort setupFree

Interactive 8-step setup wizard. Detects hardware, installs Ollama, pulls the right model for your GPU, configures MCP, and sets up content feeds. Stdlib only.

cohort codegenOllama

Generate or modify code with LLM + verification pipeline. Supports smart/smarter/smartest inference tiers. Dry-run mode available.

$ python -m cohort codegen "Add pagination to the users endpoint" \

--files src/api/users.py --mode smarter --dry-run

cohort discussOllama

Run a multi-agent roundtable discussion. Loads agent personas into a single LLM call for ~90% token reduction vs. N separate calls.

$ python -m cohort discuss "Should we add caching?" -a python_developer,security_agent,qa_agent -r 2

cohort website createOllama

Generate a static website. Runs dual roundtables (frontend + backend design), generates a unified spec, and renders via Jinja2 with link validation.

$ python -m cohort website create --name "Power Plumbing" --description "Portland plumber since 1979"

cohort migrate to-sqliteFree

Migrate from JSON file storage to SQLite. Deduplicates, verifies row counts, and renames originals to .bak.

Service Management

cohort serviceFree

Manage background services. Check status, view logs, and control service lifecycle for the Cohort server and inference backends.

status logs start stop

$ python -m cohort service status

cohort-server [OK] running on :5100

inference [OK] llama-server :8080

Cloud Providers

cohort cloudFree

Manage cloud API provider configurations. List available providers, test connectivity, and view usage budgets. Works with any provider configured via cohort secret.

providers test budget

$ python -m cohort cloud providers

anthropic [OK] configured

openai [OK] configured

google [--] not configured

$ python -m cohort cloud test anthropic

[OK] Anthropic API reachable (claude-sonnet-4-20250514)

Context Inspection

cohort contextFree

Inspect what context gets sent to the model. Shows the full prompt assembly for an agent -- system prompt, memory, channel history, and user message -- with token counts per section.

$ python -m cohort context python_developer --channel code-review

System prompt: 1,240 tokens

Agent memory: 312 tokens

Channel history: 2,841 tokens

Total: 4,393 tokens

Preference Import

cohort importFree

Import preferences and settings from other AI tools. Bring your existing configuration from Claude Code, Cursor, or other MCP-compatible tools into Cohort.

$ python -m cohort import claude-code

[OK] Imported 3 MCP servers, 12 preferences

Assessment Results

cohort assessFree

View agent assessment results. Browse scores from automated knowledge tests that validate agent expertise across their domain. Shows per-agent accuracy, question counts, and difficulty breakdowns.

$ python -m cohort assess

Overall: 95.8% (1,399 questions, 23 agents)

documentation_agent 100% (58/58)

coding_orchestrator 99% (62/63)

security_agent 99% (64/65)

--agent: Show results for a specific agent
--model: Filter by model used for assessment

Channel Hydration

cohort hydrateOllama

Seed a channel with initial discussion content. Generates contextual messages from relevant agents to prime a channel for productive conversation, using the golden pattern seed scaffold.

$ python -m cohort hydrate code-review --topic "API pagination design"

[OK] Seeded #code-review with 5 agent messages

Quiz Import

cohort quizFree

Import assessment questions for agent knowledge testing. Load question banks from YAML files, validate format, and prepare them for use with the assessment runner.

$ python -m cohort quiz import questions.yaml

[OK] Imported 58 questions for python_developer

Test Injection

cohort injectFree

Inject temporal facts into agent memory for testing. Useful for validating that agents correctly use injected knowledge in their responses without waiting for the overnight pipeline.

$ python -m cohort inject python_developer "Python 3.13 adds JIT compilation" --ttl 7d

[OK] Injected fact with 7-day TTL

Overnight Runners

cohort overnightFree

Check overnight runner status and history. View which automated pipelines ran, their results, and any failures. Covers temporal fact injection, scenario training, and health checks.

status history

$ python -m cohort overnight status

1:00 AM temporal_facts [OK] 12 facts injected

2:00 AM scenario_runner [OK] 5/5 scenarios passed

Ecosystem Inventory

cohort inventoryFree

Cross-project ecosystem inventory. Discovers tools, exports, patterns, and projects across VS Code project registry, CLAUDE.md Exports tables, and BOSS YAML inventories. Agents use this to find existing capabilities before building from scratch.

list search sources refresh

# List all inventory entries

$ python -m cohort inventory list

1. [T] llm-router

Unified local/cloud LLM routing with task-based model selection

-> tools/llm_router/llm_router.py

# Search for capabilities

$ python -m cohort inventory search "llm routing"

# Filter by type or source

$ python -m cohort inventory list --type export --source cohort

# Show where entries come from

$ python -m cohort inventory sources

By source:

BOSS 62

cohort 19

# Refresh from all sources (via server or local fallback)

$ python -m cohort inventory refresh

--type {tool,export,project,pattern}: Filter by entry type
--source NAME: Filter by source project name
--limit N: Max entries to display (default: 50)
--json: Machine-readable JSON output

Channel Sessions

cohort sessionsServer

Inspect and manage Claude Code channel sessions. Each channel gets its own Claude Code session with MCP, spawned on demand and reaped after idle timeout. View health, PIDs, heartbeat staleness, queue depths, and session thresholds.

status show reap purge

# Show all active sessions

$ python -m cohort sessions

Channel Sessions (3 total, 3 healthy)

Limit: 5 Warn: 3 Idle timeout: 600s Auto-launch: off

#code-review (1 sessions, 1 healthy, 0 queued)

[OK] a1b2c3d4e5f6 pid=12345 heartbeat=8s ago

# Inspect a specific channel

$ python -m cohort sessions show code-review

# Force-reap idle sessions

$ python -m cohort sessions reap --timeout 300

# Purge all session registrations

$ python -m cohort sessions purge

show <channel_id>: Detail for a specific channel's sessions
reap --timeout N: Reap sessions idle longer than N seconds
purge: Clear all session registrations
--json: Machine-readable JSON output

Scripting Example

Every command supports --json for easy piping. Combine commands to build custom orchestration pipelines.

#!/bin/bash
# Find the best agent, add task to queue, notify channel
TASK="Fix auth regression in /api/login"
# Find the best agent
AGENT=$(python -m cohort route "$TASK" --json | jq -r '.[0].agent_id')
# Queue it
python -m cohort queue add "$TASK" -p high -a "$AGENT"
# Post to channel
python -m cohort channel post general "Queued: $TASK -> $AGENT" --sender bot

Get Started in 30 Seconds

            $ pip install "cohort[server]" && python -m cohort setup
        

View on GitHub MCP Tools