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
- ★ 195
- Last updated
- 3mo ago
- License
- MIT
- Primary language
- Go
- FA score
- 52/100 · Major 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
- Maintenance
- Commits in the last 6 monthslast commit 2026-08-15latest release v1.0.0 (2026-07-31)+0.6 ★/day over 7 days
- Source review
- 52/100 · Major 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.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npm install -g @cohort-ai/cohort@latest
- Environment variables
DEEPSEEK_API_KEY- Runtime
- Go 1.21
- Install notes cover
- macOS
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 | 52 · Major gaps | CLIFree + model costs | ★ 195 | 3mo ago | Go | OpenAI API · Claude API |
| Piia Engram | 77 · Good | CLIFree | ★ 166 | 8d ago | Python | Codex · Claude Code |
| Yardlet | 80 · Good | Desktop appFree | ★ 36 | 1d ago | Swift | Codex · Claude Code |
| Pi Agent Desktop | 78 · Good | — | ★ 342 | 5d ago | TypeScript | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The README and SECURITY.md describe workspace tool boundaries, explicit MCP configuration, confirmation for external side effects, refusal of high-risk actions, Skill previews before installation, optional Langfuse, and sensitive-field redaction. These support partial credit. Deductions reflect that the supplied main-source sample does not expose implementation details for these controls; the security policy also warns that screenshots, OCR, AX snapshots, and local artifacts may contain sensitive information, while the runtime spans file, shell, browser, and desktop access. Evidence for least privilege and sensitive-data protection is therefore limited. The MIT license is clear, but maintainer identity and update responsibility are not.
The README and usage guide describe read-only diagnostics, explicit unavailable states, replay validation, and recovery paths; the supplied entrypoints delegate to the same CLI. Deductions reflect that the implementation sample does not show these mechanisms or concrete error handling, and the dependency list provides no availability strategy or security audit evidence. Stage and version claims are also spread across the docs, limiting confidence in self-consistency.
The docs give examples for software repositories, browser tasks, and macOS desktop use, and state boundaries for model protocols, desktop OS support, and the Chrome extension. They also describe gradual tool exposure and a separate permission gate. Deductions reflect that desktop support is limited to macOS, browser use requires manually loading an extension, and the packet does not show implementation evidence for cross-environment adaptation; routing and boundaries are mostly documented claims.
The README, usage guide, and security policy provide layered navigation, installation and configuration steps, command examples, troubleshooting guidance, known limitations, and an MIT license. Deductions reflect scattered stage and version information: the security policy lists 0.1.x support while the docs say v1.0.0 was verified. There is no clear maintainer or update responsibility statement, and the packet provides little history to assess naming stability.
The docs describe usable CLI workflows for replay, tracing, context management, and delivery that could provide audit and recovery value if implemented as stated. Deductions reflect that the sample is insufficient to confirm actual quality or user benefit; setup requires a model API, Chrome extension, and macOS permissions, and the claimed value is not independently substantiated.
Many claims are tied to commands, paths, and design documents. The docs distinguish exact offline replay from statistical live fork trials and describe how unavailable data is represented. Deductions reflect that core claims are mostly repeated across the README and guide, while the supplied main source shows only entrypoint delegation; implementation, test results, and independent corroboration are absent.
- This assessment uses only the supplied static sample; the documented security gates, replay, and recovery behavior are not independently verified by the provided implementation source.
- The runtime can access files, shell, browser, and desktop state; local screenshots, OCR, AX snapshots, and logs may also contain sensitive data.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
FAQ
Am I locked into a paid model vendor?
Does it upload my data to the cloud?
What if the agent performs a dangerous action?
Can I run it on Linux or Windows?
Does Replay guarantee exact reproduction of past behavior?
Is Cohort open source?
Is Cohort safe to use?
Is Cohort still maintained?
Who makes Cohort?
Thanks — we use this to improve the page.