kith

<p align="center"> <img src="assets/brand/readme-header.png" alt="Kith — Parallel agents. Shared direction. Local coordination for coding agents." width="100%"> </p> <p align="center"> <a href="https://github.com/connorhriley/kith/actions/workflows/ci.yml"><img src="https://github.com/connorhriley/kith/actions/workflows/ci.yml/badge.svg" alt="CI status"></a> <a href="https://github.com/connorhriley/kith/actions/workflows/windows.yml"><img src="https://github.com/connorhriley/kith/actions/workflows/windows.yml/badge.svg" alt="Windows validation"></a> <a href="https://www.npmjs.com/package/kith-coord"><img src="https://img.shields.io/npm/v/kith-coord" alt="npm version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22C55E" alt="MIT license"></a> </p> <p align="center"> <a href="#quick-start">Quick start</a> · <a href="https://marketplace.visualstudio.com/items?itemName=kith-coord.kith">VS Code</a> · <a href="https://open-vsx.org/extension/kith-coord/kith">Cursor / Open VSX</a> · <a href="#see-it-work">Demo</a> · <a href="docs/integrations.md">Integrations</a> · <a href="docs/usage.md">CLI &amp; API</a> · <a href="CONTRIBUTING.md">Contribute</a> </p>

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

| Need | Kith provides | | --- | --- | | Keep tasks from overlapping | Scoped claims with conflict responses | | Give agents separate working files | Git worktrees with an explicit integration step | | Check work before integration | Your project's verification command | | Share local tools | Port reservations and supervised command mutexes | | See what is happening | Session/task state through CLI/MCP; optional read-only editor and worktree views |

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.

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.

| Client | Setup and validation | | --- | --- | | VS Code / Cursor | One-click marketplace extension; native MCP controls retain approval and trust | | Claude Code / Claude Desktop / Codex | Detected client configuration through kith setup | | Other MCP clients | stdio server via kith mcp; client-specific validation required |

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