# Cork for AI agents

<!--
title: "Cork for agents"
description: "How an AI coding agent should use Cork, step by step: the briefing, the write gate, deltas, messages, notes and the REST API."
canonical: "https://corkcli.com/agents.md"
last_updated: "2026-11-13"
-->

Cork (https://corkcli.com) catches the collisions git can't see: git tells you when two agents touched the same line, Cork tells you when they touched the same idea. It hands each agent working on the same codebase one shared map of the code and what the others already changed and learned. It works with Claude Code, Codex, Cursor, Hermes, Gemini CLI, VS Code and Copilot, Windsurf, claude.ai, ChatGPT and any MCP client. It does not run agents or host code: your agents keep running where they already run.

## When to use Cork

- More than one agent (or an agent and a person) edits the same repository at the same time.
- An agent should know what teammates changed recently before it edits: signatures, callers, renames.
- A team wants one place to see every agent's work, collisions and decisions.

## Connect

- MCP server (Streamable HTTP): `https://mcp.corkcli.com`
  - Claude Code: `claude mcp add --scope user --transport http cork https://mcp.corkcli.com`
  - Codex: `codex mcp add cork --url https://mcp.corkcli.com`, then `codex mcp login cork`
  - Gemini CLI: `gemini mcp add --transport http cork https://mcp.corkcli.com`
  - Hermes: `hermes mcp add cork --url https://mcp.corkcli.com --auth oauth`
  - Cursor and VS Code: their install links on [corkcli.com](https://corkcli.com) open with Cork filled in, or add a remote MCP server with the URL above
  - claude.ai and Claude Desktop, ChatGPT, Windsurf (now Devin Desktop) and any other MCP client: add a custom connector or remote server with the URL above
- Whole machine, every repo (hooks for Claude Code, Codex, Cursor and Hermes): `curl -fsSL https://corkcli.com/install.sh | sh`, or `npx corkcli`
- Cork's official agent skills (setup, briefings and the write gate, handoffs and messages, what Cork recorded), for any agent that reads skills: `npx skills add corkcli/cork`

Sign-in is OAuth 2.1 with PKCE and needs no API key: see [auth.md](https://corkcli.com/auth.md).

## What an agent does with it

1. Read the briefing Cork hands you at session start and with each prompt: exact signatures, callers and recent changes of the code you are about to touch. Build on it instead of re-reading files.
2. Write as usual. Every write is checked against teammates' live changes; if one collides, the tool result says who and what. Adapt to it, then retry.
3. Lines starting with Δ in a tool result are teammates' changes since your last step: adapt to them, never undo them.
4. Use the MCP tools when they add something: `get_symbol`, `blast_radius` (what a change breaks), `recap` (what happened and what it cost), `remember` / `recall` (notes anchored to code), `send_agent_message` (reach whoever works on a symbol).

## REST API

- Base URL `https://api.corkcli.com/api/v1`, described by [openapi.json](https://corkcli.com/openapi.json); docs: [docs/api.md](https://corkcli.com/docs/api.md).
- Versioned in the path; unversioned `/api/...` paths are deprecated aliases. Policy: [docs/api/versioning.md](https://corkcli.com/docs/api/versioning.md).
- `Authorization: Bearer <token>` (OAuth 2.1 access token, or the machine credential from `cork login`).
- Retries: send `Idempotency-Key` on writes. Rate limits: read the `RateLimit` headers and honour `Retry-After` on a `429`.
- Long operations: `POST /api/v1/jobs` or `Prefer: respond-async`, then poll the `Location` until the job finishes.
- Plans and credential URLs without signing in: `https://api.corkcli.com/api/v1/plans`.
- Cork not answering? Read [status.json](https://corkcli.com/status.json) (no credential): `status.indicator` is `none` when everything is operational; otherwise `components` says which part is down and `incidents` what is being done. The hooks fail open, so your work continues either way.

## Plans

Pay for agent hours (time the model is thinking and writing), not seats. Free: 10 agent hours a month per account, unlimited repos and agents, no card; one machine with no account is free too. Then $20 a month per unit of 100 hours pooled across the workspace, graduated to $17 and $15, 15% off a year. Details: [pricing.md](https://corkcli.com/pricing.md).

## More

- [llms.txt](https://corkcli.com/llms.txt) and [llms-full.txt](https://corkcli.com/llms-full.txt)
- [OpenAPI](https://corkcli.com/openapi.json) for the REST API v1 at https://api.corkcli.com/api/v1
- [Source and skills on GitHub](https://github.com/corkcli/cork): the hooks, parser, protocol, local engine and plugin, with an AGENTS.md for agents working on them
- [Docs](https://corkcli.com/docs) · [Benchmarks](https://corkcli.com/benchmarks) · [Support](https://corkcli.com/support) · [Status](https://corkcli.com/status)
