Cohort
A local-first, evidence-driven Agent Runtime that records verifiable execution traces, forks historical runs for counterfactual experiments, and governs context, cost, and tool risk.
- Source repo
- congchuanling-dot/Cohort
- Stars
- ★ 186
- Last updated
- 2mo ago
- License
- MIT
- Primary language
- Go
- FA score
- 68/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An engineer inheriting an unfamiliar repository: Cohort reads README, go.mod, and source directories through governed file tools and produces architecture summaries and prioritized improvements grounded in specific files, not superficial README paraphrases.
- Not a fit if
- Teams needing Linux or Windows desktop automation
- Users wanting zero-setup browser automation without loading an unpacked extension
- Teams requiring native Gemini, Bedrock, Vertex, or Azure adapters
- Source review
- 68/100 · Some gaps
What does this agent do, and when should you use it?
Cohort is a local-first Agent Runtime written in Go and distributed via npm, positioned as the runtime layer between large language models and real execution environments. It controls a real browser through a Chrome Bridge extension, performs controlled macOS desktop operations via the Accessibility (AX) tree, integrates external systems through MCP, and executes file, shell, and memory operations through a governed tool layer. Its key differentiator is the Time Machine: every run is recorded as a Replay Bundle with SHA-256 proofs, which can be verified offline via Exact Replay or forked at a specific turn inside an isolated Git Worktree to swap models or system prompts and repeat trials. The Runtime Governor builds a control plane on the immutable run.log.jsonl evidence stream, governing provider receipts, context capacity, cost, and repeated failures, and reconstructs a drillable Causal DAG. The model layer connects by protocol — OpenAI-compatible Chat Completions and the Anthropic Messages API — supporting local models (Ollama/LM Studio) and multi-profile fallback; long-term memory must cite tool evidence, be read back after write, and produce audit records. It is currently in public preview: desktop capability is macOS-focused, and high-risk actions such as payments, approvals, and deletions are refused outright.
Users enter an interactive REPL via cohort or run one-shot tasks with cohort ask "task". The Agent Runner loads session history, memory.md, and compact.md, constructs a budgeted context window, asks the active LLM provider (openai or anthropic protocol) for tool decisions, and executes through the governed tool layer: file_read/file_write/file_patch, code_run, 60+ browser_* tools (operating page DOM via the Chrome Bridge extension on ws://127.0.0.1:18777/browser), desktop_* tools (macOS AX snapshots, keyboard, OCR), MCP tools, and memory_propose_update/memory_apply_update. Every run records requests, responses, tool observations, prompts, and workspace snapshots into a Replay Bundle: cohort trace replay exact <session_id> --run <run_id> verifies frame-level hashes offline and stops at the first divergence; cohort trace replay fork ... reuses recorded evidence up to the fork point, then switches to a live model, repeating trials in an isolated Worktree and reporting success rate, tokens, latency, and a Proof Hash. The Runtime Governor maintains a Provider Receipt Ledger, a Context Capacity waterfall, an executable Policy Engine, and a Causal DAG (cohort trace graph last --open renders an offline HTML). The Evidence Delivery flow uses cohort deliver plan/run/review/accept to build candidates in isolated worktrees, run an independent Verifier, and merge transactionally after human approval. All evidence is written locally under temp/sessions/<session_id>/, with optional Langfuse tracing.
- An engineer inheriting an unfamiliar repository: Cohort reads README, go.mod, and source directories through governed file tools and produces architecture summaries and prioritized improvements grounded in specific files, not superficial README paraphrases.
- A frontend acceptance tester: the Chrome Bridge performs login-form DOM checks, real CDP input, and post-action verification via an open -> wait -> dom_summary -> act -> verify loop instead of screenshot scripts.
- A team comparing model or prompt changes: Fork Replay switches to a candidate model at a chosen turn inside an isolated Worktree, repeats trials, and compares success rate, tokens, and first behavioral divergence.
- A macOS power user automating desktop apps: the AX control tree locates windows and controls to draft messages; external side effects require explicit confirmation, and payments/deletions are refused.
- An engineering lead needing auditability: immutable run.log.jsonl, provider receipt distinctions, the Causal DAG, and memory audit logs answer "what happened and can it be tampered with?".
- Multi-agent software delivery: Acceptance Contracts, an isolated Builder, and an independent Verifier produce evidence-hashed candidate changes merged transactionally after human approval.
How do you install or deploy this agent?
Recommended npm global install (the package downloads a macOS-architecture binary from GitHub Releases, verifies SHA256, and bundles the Chrome Bridge extension, macOS desktop helper, and OCR helper; verified version v1.0.0):
bash
npm install -g @cohort-ai/cohort@latest
cohort --versionOr use the GitHub installer:
bash
curl -fsSL https://raw.githubusercontent.com/congchuanling-dot/Cohort/master/scripts/install.sh | sh -s -- --repo https://github.com/congchuanling-dot/Cohort.git
export PATH="$HOME/.cohort/bin:$PATH"Source development requires Go 1.21:
bash
git clone https://github.com/congchuanling-dot/Cohort.git
cd Cohort
./scripts/install.shThen run cohort init --provider deepseek (or local / anthropic), set the matching API key environment variable, and run cohort doctor for a pre-flight diagnosis.
How do you use this agent?
- Configure the model API and inject the key, e.g. DeepSeek:
cohort init --provider deepseek && export DEEPSEEK_API_KEY="sk-xxx"; use--provider localfor Ollama/LM Studio OpenAI-compatible endpoints;--provider anthropicfor Claude. - Browser automation: run
cohort extension opento open chrome://extensions, enable Developer mode, Load unpacked the directory printed bycohort extension path, then verify withcohort doctor computershowing browser.bridge.connection: connected. - Desktop automation: grant Accessibility and Screen Recording permissions to the terminal running Cohort in macOS System Settings.
- Start: run
cohortfor interactive mode and type a task, orcohort ask "Read README.md and summarize core capabilities". Useful commands includecohort tools,cohort config,cohort session list/resume,cohort mcp add/list/status,cohort skill list,cohort trace graph last --open,cohort trace replay exact/fork,cohort deliver plan/run/review/accept, andcohort ui(local Control Center). Optional Langfuse tracing is enabled via COHORT_LANGFUSE_ENABLED and related environment variables.
What are this agent's strengths and limitations?
- Time Machine is a concrete differentiator: Exact Replay verifies frame and aggregate hashes fully offline, and Fork Replay runs repeatable counterfactual experiments in isolated Worktrees with Proof Hashes — most agent frameworks offer no verifiable causal replay.
- The model layer connects by protocol rather than vendor lock-in: native OpenAI-compatible and Anthropic adapters, runnable on local Ollama/LM Studio, with multi-profile fallback and no cloud control plane dependency.
- Clear governance and safety boundaries: R1/R2/R3 risk tiers, ask_user confirmation tokens for external side effects, outright refusal of payments/approvals/deletions; long-term memory must cite tool evidence, be read back, and be audit-logged.
- Adaptive tool routing has measured results: coding tasks reduce 81 to 15 tools with an 82.6% schema payload reduction, avoiding full-schema injection into every request.
- Desktop Computer Use is macOS-only; cross-OS drivers are still on the roadmap, so Linux/Windows users get no desktop automation.
- Browser automation requires manually loading an unpacked Chrome Bridge extension plus system permissions — higher setup cost than pure API tools.
- No built-in adapters for Gemini native API, Bedrock, Vertex, or Azure OpenAI special auth/paths; these can only be reached through OpenAI-compatible gateways.
- Public preview stage (v1.0.0 verified); Fork Replay's live suffix is explicitly non-deterministic and requires repeated trials for statistical conclusions, and there is no third-party audit or production-scale adoption evidence.
How does this agent compare with similar options?
The README contrasts itself with generic "agent demos / chat wrappers" and describes its Skill system as working "like Claude Code" for installing, verifying, and pinning workflows, but it does not systematically compare against specific competitors.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Cohort This agent | 68 · Some gaps | CLIFree + model costs | ★ 186 | 2mo ago | Go | OpenAI API · Claude API |
| Piia Engram | 88 · Good | CLIFree | ★ 163 | 2d ago | Python | Codex · Claude Code |
| Remnic Agent Memory | 85 · Good | CLIFree + model costs | ★ 229 | 1d ago | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
| Emulo | 78 · Good | Agent plugin / skillFree + model costs | ★ 299 | 12d ago | HTML | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows a tiered permission model (R1 reversible / R2 external effects with one-time confirmation token / R3 high-risk refusal), local-first storage, opt-in Langfuse tracing, and evidence-bound memory writes with read-back confirmation. Deduction: these are self-described in README/SECURITY.md; the provided source sample omits the tool-layer implementation, so actual enforcement of R1/R2/R3 and the confirmation token mechanism could not be inspected. Source attribution is only 'Cohort contributors' with an unverified publisher.
go.mod shows a minimal dependency set of well-known libraries and CI runs go test; cohort doctor plus troubleshooting steps (e.g., browser bridge connectivity checklist) support diagnosable failures. Deduction: no test files supplied, so coverage is unverifiable; SECURITY.md lists supported version 0.1.x while README claims verified v1.0.0 — inconsistent versioning.
Audience and scenarios are well documented (CLI agent, Control Center, browser/desktop automation, multi-agent delivery); the 'current boundaries' section candidly lists macOS-only desktop use, missing Gemini/Bedrock/Vertex adapters, and non-deterministic fork suffixes. Deduction: environment fit is limited to macOS today; routing claims (81→15 tools) are self-reported without independent support.
README is thorough (quick start with verification commands, architecture, capability matrix, security model links), multi-language READMEs, MIT LICENSE present. Deduction: no CHANGELOG; SECURITY.md version table (0.1.x) contradicts README's v1.0.0; maintenance responsibility is only 'best-effort' with no named maintainers.
Clear differentiated value proposition (verifiable replay, runtime governance) with concrete CLI output shapes, example tasks, and acceptance commands. Deduction: core differentiation claims (SHA-256 proofs, routing compression rates, delivery loop) rely on self-description and design docs not included in the reviewed files; no quantified cost/benefit or third-party evaluation.
Fact/inference separation is relatively good (distinguishing provider receipts from local estimates, deterministic prefix vs statistical suffix, marking missing data as unavailable). Deduction: key claims (hash verification, isolated worktrees, cost governance) point to documents not in the reviewed file set, preventing cross-checking; no external benchmarks or third-party corroboration.
- Publisher identity is unverified and the installer uses a curl | sh pattern; review scripts/install.sh before executing.
- The security model (R1/R2/R3, confirmation tokens, redaction) is documented self-description only; static review could not verify implementation — audit internal/tools and internal/desktop before use with sensitive data.
- Desktop automation requires granting Accessibility and Screen Recording to the host terminal; permission surface is large, run in a dedicated workspace.
- SECURITY.md lists supported version 0.1.x while README claims v1.0.0; note the version/support mismatch.
- Confirm data boundaries before enabling Langfuse; screenshots and AX snapshots may expose sensitive local state.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.