Kith

Local coordination for cooperating coding agents.

Claim work, isolate changes with Git worktrees, share local resources, and verify integration—without a hosted service.

One agent changes an interface while another builds against it. Two agents edit the same file. Separate worktrees still compete for a dev-server port or a package install.

Kith gives cooperating agents shared local state: who owns a task, which files are claimed, and which commands need to wait. Agents use its MCP server; CLI commands support local inspection and maintenance. Coordination lives in SQLite on your machine; Kith itself needs no hosted service or model API key.

What Kith does

Kith fits workflows where you already launch multiple coding agents and want them to coordinate. It does not choose models, write prompts, or launch a fleet for you. Worktrees separate files; Kith adds shared ownership and resource coordination.

The reliability contract defines ownership, verification, recovery and enforcement boundaries. Claims coordinate cooperating clients; hooks do not sandbox filesystem access. Scope matching follows a documented grammar. Contract-change reports and exact-name reuse hints are advisory.

Related MCP server: coordinaut

Quick start

Requires Git 2.38+ and Node.js 22.13+ on 22.x or Node.js 24+. Full workflows target macOS and Linux. Native Windows MCP checks cover claims, worktrees, ports, integration and recovery; supervised mutex commands and shell hooks require macOS/Linux or WSL. See the support evidence.

Git recording and integration require a commit identity configured for the repository (user.name and user.email). Kith does not change your global Git identity.

Upgrading to 0.1.6: Stop existing Kith connections first. Back up stopped coordination state (including SQLite sidecars) and retain worktrees; upgrade all coordinators sharing a repository together. This release migrates storage schema 2 to 3, which older binaries refuse. Existing custom launchers are preserved; review their pinned version before reconnecting. See recovery guidance.

VS Code or Cursor

Install Kith (kith-coord.kith) from the VS Code Marketplace or Cursor / Open VSX. You can also search for kith-coord.kith in the editor's Extensions view.

To select release 0.1.7 explicitly with an editor CLI already on your PATH:

code --install-extension kith-coord.kith@0.1.7
cursor --install-extension kith-coord.kith@0.1.7

Use the command for your editor. A marketplace lookup can temporarily select an older version; the extension guide also links the published 0.1.7 VSIX.

Open a trusted local Git checkout and approve Kith's MCP server through the editor. The extension bundles the coordination server, detects Node, and preserves existing MCP entries, hooks and tool permissions. No global npm install is needed. Each agent still needs to use Kith's tools; installing the extension does not enforce claims on other writers.

Start with a scoped task:

Use Kith to begin an isolated task in this repository with a unique agent ID.
Claim only the files this task needs, edit the returned worktree, and report edits.
Run the project checks and complete through Kith with that verification command.

The extension guide covers settings and existing configurations; recorded editor checks distinguish installation, native MCP registration and signed-in task results.

CLI and other MCP clients

One command from your Git checkout configures supported detected clients and adds project instructions:

npx --yes --package kith-coord@0.1.7 kith setup

Durable setup starts with 0.1.7. Earlier versions need a persistent global npm installation before setup. Client setup covers configuration scope and advanced options.

Setup retains an exact self-contained runtime outside npx's cache, checks its MCP discovery, and backs up changes before writing them. On macOS, the next release also opens read-only Radar automatically; use --no-radar for MCP-only setup. Existing custom Kith launchers, peer servers, hooks and permissions are preserved. From outside a Git checkout it configures global connections; pass a project path to add that project's guidance. Reconnect the client and approve its MCP server through the client's normal controls.

Ask your agent to do the task using Kith. The view says Watching only until a task is actually recorded. A configured server is not a running task. kith setup --dry-run previews without writes; kith doctor /absolute/checkout diagnoses configuration.

For source installation and the disposable demo, use the pinned pnpm 10.20.0:

git clone https://github.com/connorhriley/kith.git
cd kith
corepack enable
pnpm install --frozen-lockfile
pnpm build

See it work

pnpm demo

The demo starts two real MCP clients, gives each a separate Git worktree in a temporary repository, refuses an overlapping claim, records their edits, runs commands under a mutex, and verifies/integrates both changes. It removes the temporary repository afterward. No model calls or client credentials are needed.

auth: claimed src/auth.mjs in an isolated worktree
billing: overlapping claim on src/auth.mjs refused
billing: claimed src/billing.mjs in an isolated worktree
auth: checked its worktree through the MCP command supervisor
auth: isolated edit reported, verified, and integrated
billing: checked its worktree through the MCP command supervisor
billing: isolated edit reported, verified, and integrated
Two real MCP clients completed work in separate worktrees. Disposable example passed.

The implementation is in examples/two-agents.mjs. This demonstrates the coordination protocol; native-client validation separately exercises installed coding clients.

Client support

The editor extension bundles the server and offers it through native MCP registration; no global npm install is needed. Installing an extension or writing configuration does not enforce claims on writers that do not use Kith. Existing custom Kith entries retain precedence.

Native evidence is version-specific. See client validation, advanced integration setup and session ownership. The npm package is kith-coord and the command is kith; the unrelated npm package kith is not this project.

Dev servers and shared config

In version 0.1.4, kith dev runs a server with its allocated PORT and supports explicit {port} arguments. File claims also accept an optional bounded wait:

kith dev --agent web-a -- npm run dev -- --port '{port}'
# Within an existing owned session:
kith lock acquire --agent worker-1 --scope package.json --wait --wait-ms 30000

See dev-server launch and waiting claims for framework flags, session setup, cancellation, and MCP usage.

Read-only Radar

In the next release, macOS setup opens Radar in the menu bar for the selected checkout or workspace. It uses the retained installation, so clearing the npx cache does not break it. Repeat setup keeps an existing Radar workspace selected. Use Switch Workspace in its menu to change it.

kith setup --no-radar configures MCP without opening Radar (useful on headless machines); --dry-run never launches it. Linux and Windows skip the menu-bar view. Setup does not add a login item; after quitting, reopen with:

kith watch /path/to/workspace --once --json
kith menubar /path/to/workspace  # macOS 12+, Intel or Apple Silicon

The menu and editor lead with recorded tasks, current file claims, shared-resource waits and integrations that need inspection. A registered session without a task is shown separately. Saved checkouts and path comparisons stay in details; nothing is automatically deleted. The menu's default view omits the file-timestamp feed.

Watching only means no active Kith task is recorded. Shared dirty paths are files to review before integration, not a proven merge conflict. Status unavailable remains explicit when state cannot be inspected safely. Reads use private snapshots without renewing owners or migrating the original database. See observation limits.

How a task moves through Kith

1. Begin through MCP. Call kith_begin_work with a unique agentId, explicit scopeGlobs, and isolateWorktree: true. The connection retains session ownership; no shell exports are needed for this MCP-only workflow.

2. Claim a scope. Cooperating clients receive a conflict when an exclusive claim overlaps another claim.

3. Do the work. Edit the returned worktree.worktreePath, report edits with kith_record_file_edit, and use kith_run_with_mutex for serialized commands. Heartbeat before expiry and keep the owning connection open.

4. Verify and complete. For a worktree, Kith checkpoints changes and integrates through a separate staging worktree. The target must be clean. Supply a verification command to check more than Git mergeability.

Failed verification leaves the target unchanged and keeps the worktree for repair. Successful integration also retains the worktree until explicit cleanup. External Git writers must still coordinate.

Inspect through kith_get_status or kith status: worktree paths/branches, dirty-file overlap, ahead/behind, heartbeat/commit age and FIFO waiters are included. Use kith_preview_integrate for committed-tree conflict paths before completing. Normal status may reap expired owners. For non-mutating recovery inspection use:

kith status --offline
kith recover
kith doctor

Optional Claude/Cursor hooks support --enforcement block (default), warn and off; see setup and safe uninstall. The versioned protocol records the tool schemas and ownership semantics.

For MCP, CLI and library examples, see workflows.

Project status

The suite exercises process contention, session ownership, command cancellation and disconnects, generated hooks, MCP workflows, and worktree integration. Clean-package checks install the built distribution in a separate consumer project. Native-client reports include exact versions and outcomes.

The CI badge links to current hosted results; local tests and recorded native runs do not establish that every platform or client release passes. Repository discovery, physical path checks, exact supported glob matching and Git conflict refusal have dedicated regressions. Recovery checks cover interrupted upgrades, stopped database/WAL backups and retained worktree continuation. The reliability contract records the boundaries of those scenarios; native-client coverage is listed above.

• Reliability contract: behavior, boundaries, and recovery

• Architecture: storage, adapters, and Git integration

• Roadmap: priorities and completion gates

• Changelog: behavior changes and migration notes

Contributing

The most useful contributions reproduce a concrete failure or improve a real multi-agent workflow. Include a disposable fixture, expected behavior, and a way to verify the change. Start with contributor setup and entry points.

For bugs, use the bug report form. For a proposed workflow, use the feature request form. Keep tokens, source snapshots, and .coord state out of public diagnostics; use the security reporting guidance for sensitive reports.

MIT licensed. Participation follows the community expectations.