# Cork (agent mode)

<!--
title: "Cork: agent mode"
description: "Cork for agents: what it is, when to use it, MCP, REST API, service status, auth, pricing, free tier, install, rate limits, idempotency, versioning and async jobs."
canonical: "https://corkcli.com/?mode=agent"
last_updated: "2026-10-22"
-->

Cork 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. For AI coding agents (Claude Code, Codex, Cursor and any MCP client) on one codebase, on one machine or across a team.

## What it does

- Catches: a rename, removal or signature change reaches every agent that calls the code on its next step; once a rename is pushed, a write to that file is stopped once (the retry goes through); semantic lint checks every write; two agents on the same task are told.
- How: hooks report each agent's reads, edits and commands; each session and prompt starts with the exact signatures, callers and recent changes of the code it is about, from one shared map of the repo; `git push` is one step (rebase, test, push).
- Saves: 53% fewer tokens with 12 agents on one repo (Study 5); 5.3x fewer tokens per agent on the AI model bill, with Cork vs without (Study 2): https://corkcli.com/benchmarks

## When to use Cork

- Several agents, or several people's agents, edit the same repository at once.
- You want a rename, removal or signature change in one agent's work to reach the other agents that use it while they are still working, not at merge time.
- You want an agent to know who else is changing the code it is about to touch, and what changed (renames, new signatures) since it last looked.
- You want a rebase, test and push in one step instead of a reject-pull-retest loop.
- You want durable team notes anchored to code, and messages between agents.

Not for: running or hosting agents (your agents keep running where they run).

## Install

- Every repo on a machine, free, no account: `curl -fsSL https://corkcli.com/install.sh | sh` (or `npx corkcli`)
- MCP only: `claude mcp add -t http cork https://mcp.corkcli.com` (Claude Code), `codex mcp add cork --url https://mcp.corkcli.com` (Codex)
- Install docs: https://corkcli.com/install

## MCP

- Endpoint (Streamable HTTP): https://mcp.corkcli.com
- Tools, input schemas and annotations: https://corkcli.com/.well-known/mcp.json
- Server card: https://corkcli.com/.well-known/mcp/server-card.json
- Tools reference: https://corkcli.com/docs/mcp-tools.md

## API

- REST API base: https://api.corkcli.com/api/v1
- OpenAPI 3.1: https://corkcli.com/openapi.json
- API catalog (RFC 9727): https://corkcli.com/.well-known/api-catalog
- API docs: https://corkcli.com/docs/api.md
- Health of the server alone: https://api.corkcli.com/api/v1/health

## Status

- Status page: https://corkcli.com/status
- JSON (Statuspage-style): https://corkcli.com/status.json: `status.indicator` none, minor, major or critical; `components[].status` operational, degraded_performance, partial_outage or major_outage, each from checks that ran; `components[].uptime` with its window and `tracking_since`; `incidents[]`.
- Markdown: https://corkcli.com/status.md
- Incident feed (Atom): https://corkcli.com/status/feed.xml
- The server's own record (no credential): https://api.corkcli.com/api/v1/status

## Auth

- OAuth 2.1 authorization code flow with PKCE (S256); scope `collide`.
- Dynamic client registration (RFC 7591): https://mcp.corkcli.com/register
- Authorization server metadata: https://mcp.corkcli.com/.well-known/oauth-authorization-server
- Protected resource metadata: https://mcp.corkcli.com/.well-known/oauth-protected-resource
- Use: `Authorization: Bearer <token>` (OAuth access token `cat_...`, 24 hours, refreshed with `crt_...`; or the machine credential `cork login` stores in `~/.cork/credentials.json`).
- Self-serve: sign-up and OAuth need no API key request, form or sales call. Walkthrough: https://corkcli.com/auth.md

## Pricing

- Cork, free and local: $0, no account; unlimited agents and repos on one machine; data stays on the machine.
- Cloud Free: $0; 10 agent hours a month per account plus 30 bonus hours the first month and 10 when an invited teammate joins. An agent hour is time the model is thinking and writing; a tool's run time, typing and idle time never count. Unlimited repos and agents, 30-day history window.
- Agent hours: $20 per month per unit of 100 agent hours, pooled across the workspace, unlimited parallel agents, no per-person caps. Graduated: units 1-10 at $20, 11-50 at $17, 51+ at $15 (5 units $100, 10 units $200, 25 units $455, 50 units $880). Annual 15% off. Alerts at 80% with the projected run-out day; at 100% running sessions finish inside a 10% grace band and new sessions wait; past the band every session stops after its current step. Optional auto top-up and spend cap.
- Enterprise: from about 100 units; custom pooling, VPC or self-hosted, SOC 2, custom retention.
- Seat plans bought before agent hours (Team $10/seat, Business $45/seat) keep their price, unmetered, until 2027-11-01; moving to agent hours before then takes 20% off the first year.
- Machine-readable plans and credential URLs, no sign-in: https://api.corkcli.com/api/v1/plans
- Pricing page: https://corkcli.com/pricing.md

## Free tier

Cork, free and local, runs entirely on one machine with no account and no key (install command above). Cloud Free is one person with unlimited repos and agents. Sign-up is self-serve.

## Rate limits

- REST: per caller, a bucket of 600 requests refilling at 10 per second.
- Agent routes: the workspace's plan (Free 8/s, burst 120; paid (agent hours) 60/s, burst 600; Enterprise unmetered).
- Headers: `RateLimit-Policy`, `RateLimit`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`; over the limit `429` with `Retry-After`.
- Usage reports are never rate-limited.

## Idempotency

`Idempotency-Key` on any POST, PUT, PATCH or DELETE: the same key and request within 24 hours replays the first response (`Idempotent-Replayed: true`); the same key with a different request is `422`; scoped per caller.

## Versioning

Path versioning: `/api/v1`, `API-Version: 1` on every response. Unversioned `/api/...` paths are deprecated aliases (`Deprecation` and `Link: rel="successor-version"` headers). Breaking changes only in a new major version, with at least six months' notice and a `Sunset` header. Policy: https://corkcli.com/docs/api/versioning.md

## Async jobs

`POST https://api.corkcli.com/api/v1/jobs` (operations: graph-export, waste-report, repo-clear, inbox-wait, land-turn) or `Prefer: respond-async` on the endpoint: `202 Accepted` with `Location: /api/v1/jobs/{id}`; poll `GET /api/v1/jobs/{id}` (queued, running, succeeded, failed, cancelled); `DELETE` cancels.

## Docs

- Docs: https://corkcli.com/docs.md
- llms.txt: https://corkcli.com/llms.txt
- agents.md: https://corkcli.com/agents.md
- skill.md: https://corkcli.com/skill.md
- Sitemap: https://corkcli.com/sitemap.xml
- Support: https://corkcli.com/support
- Status: https://corkcli.com/status
