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.
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.
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.l 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.l, 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.
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 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.
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.