ctxcohere

ctxcohere is a local-first context coherence layer for AI agents.

AI agents often act on stale information. They read files, tool results, MCP schemas, package manifests, or retrieved docs, then keep working after those sources have changed. ctxcohere records what an agent has already consumed and blocks risky actions when that context is no longer true.

What It Does

• Runs agents inside managed git worktrees.
• Records source baselines and explicit context observations.
• Hashes files with BLAKE3 and stores state locally in SQLite.
• Blocks risky patch promotion when touched files or their import dependencies changed.
• Exposes MCP tools over stdio and Streamable HTTP.
• Ships a TypeScript SDK for JS-based integrations.
• Provides a terminal dashboard with ctxcohere tui.

Install

From this repository:

cargo install --path crates/ctxcohere-cli

For JavaScript integrations:

pnpm install
pnpm --filter @ctxcohere/sdk build

Quickstart

ctxcohere init
ctxcohere run -- <agent-command>
ctxcohere apply

Example with a shell command standing in for an agent:

ctxcohere run -- sh -c "printf 'agent edit\n' > README.md"
ctxcohere apply

During run, ctxcohere creates .ctxcohere/worktrees/<session>. The agent edits that sandbox. ctxcohere apply promotes the sandbox patch back into the real repository only if the relevant context is still coherent.

Commands

Command	Purpose
ctxcohere init	Create .ctxcohere.toml and example policy files.
ctxcohere run -- <cmd>	Start a supervised agent session in a managed worktree.
ctxcohere apply [session]	Check coherence and promote a sandbox patch.
ctxcohere status --json	Show local state and stale-context count.
ctxcohere inspect	List stale context.
ctxcohere replay	Print the local JSONL event stream.
ctxcohere watch	Record live source-change events.
ctxcohere tui	Open the terminal dashboard.
ctxcohere policy test	Test policy decisions from the CLI.
ctxcohere adapter install <name>	Write adapter config for Codex, Claude Code, Cline, OpenHands, or generic MCP clients.
ctxcohere mcp proxy	Serve ctxcohere MCP tools over stdio.
ctxcohere mcp proxy --transport streamable-http	Serve ctxcohere MCP tools over HTTP/SSE.

MCP Tools

• ctxcohere.record_context
• ctxcohere.check_action
• ctxcohere.explain_stale
• ctxcohere.refresh_plan
• ctxcohere://status

TypeScript SDK

import { CtxCohereClient } from "@ctxcohere/sdk";

const ctx = new CtxCohereClient("http://127.0.0.1:8787/");

await ctx.recordContext({
  path: "src/auth.ts",
  summary: "agent read auth flow"
});

const decision = await ctx.checkAction({
  paths: ["src/auth.ts"],
  risk: "high"
});

if (!decision.allowed) {
  console.log(decision.reason);
}

Documentation

• Architecture
• MCP integration
• Policy
• Adapters
• Security model
• Threat model
• Field testing
• Stale-context demo
• Contributing

Development

cargo fmt --all --check
cargo clippy --workspace -- -D warnings
cargo test --workspace
pnpm typecheck
pnpm test
cargo deny check advisories licenses sources
scripts/field-test.sh
scripts/agent-smoke.sh
scripts/agent-task-matrix.sh
scripts/stale-block-test.sh

Release

The repository includes:

• GitHub Actions CI in .github/workflows/ci.yml.
• Tag-based binary release automation in .github/workflows/release.yml.
• A source-based Homebrew formula in packaging/homebrew/ctxcohere.rb.
• scripts/release-sha256.sh for release checksum generation.

License

Licensed under the MIT License. See LICENSE.