wit

KO | EN

gitlite — search

#python #php #javascript #nodejs #java #go #ruby #scala #chrome-extension #oauth2 #wordpress #bundle

★ 46 Open GitHub ↗

Agent coordination protocol — declare intents, lock symbols, detect conflicts before code is written

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<img src="logo.png" alt="wit" width="400" />


 Agent coordination protocol for shared codebases


 Declare intents. Lock symbols. Detect conflicts. Before code is written.


 <a href="https://github.com/amaar-mc/wit/actions/workflows/ci.yml"><img src="https://github.com/amaar-mc/wit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
 <a href="https://www.npmjs.com/package/wit-protocol"><img src="https://img.shields.io/npm/v/wit-protocol" alt="npm"></a>
 <a href="https://github.com/amaar-mc/wit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/amaar-mc/wit" alt="License"></a>
 <a href="https://github.com/amaar-mc/wit/stargazers"><img src="https://img.shields.io/github/stars/amaar-mc/wit?style=social" alt="Stars"></a>

---

**Wit** coordinates multiple AI coding agents working on the same repository simultaneously. It sits between your agents and git — git handles version control, Wit prevents the conflicts.

The name comes from the word itself: the intelligence to coordinate before colliding. It also stands for **W**orkspace **I**ntent **T**racker.

## The Problem

You have three Claude Code instances (or Cursor, Copilot, Devin — any combination) working on the same repo. Without coordination, they each write code independently and produce merge conflicts that waste time and break work.

Git detects conflicts **after** they happen. Wit prevents them **before** code is written.

## How It Works

Wit runs a lightweight daemon in the background. Agents communicate with it over a Unix socket using JSON-RPC. The daemon tracks four things:

| Primitive | What it does | Example |
|-----------|-------------|---------|
| **Intents** | Agent announces planned work scope | "I'm refactoring the auth module" |
| **Locks** | Agent reserves a specific function/type/class | Lock `src/auth.ts:validateToken` |
| **Conflicts** | Daemon warns when intents or locks overlap | "Agent B also declared intent on auth.ts" |
| **Contracts** | Agents agree on function signatures | "validateToken accepts string, returns boolean" |

Intents and locks are **warnings, not blocks**. Agents always get to decide what to do. The only hard enforcement is contracts — a git pre-commit hook blocks commits that violate an accepted contract signature.

## Quick Start

### Prerequisites

Wit requires [Bun](https://bun.sh) (v1.0+). It uses Bun-native APIs for the daemon, SQLite, and process management. Install Bun if you don't have it:

```bash
curl -fsSL https://bun.sh/install | bash
```

### Install the CLI

**From npm:**
```bash
bun install -g wit-protocol
```

**From source:**
```bash
git clone https://github.com/amaar-mc/wit.git
cd wit
bun install
bun link
```

After either method, the `wit` command is available globally.

### Initialize in your repo

```bash
cd your-project
wit init
```

This creates a `.wit/` directory, starts the daemon, and generates a `CLAUDE.md` with coordination instructions. You only run this once per project — the daemon auto-starts on subsequent commands.

Every Claude Code session in this project will now automatically read the `CLAUDE.md` and follow the coordination protocol. Agents declare intents, lock symbols, and respect conflicts without any manual setup.

### Basic workflow

```bash
# See what's happening
wit status

# Declare intent before working
wit declare --description "Adding rate limiting to API" --files src/api.ts --files src/middleware.ts

# Lock a specific function you're about to modify
wit lock --symbol "src/api.ts:handleRequest"

# Check status — your intent and lock are visible to all agents
wit status

# Release when done
wit release --symbol "src/api.ts:handleRequest"

# Watch live updates (like htop for coordination)
wit watch
```

### What agents see

When Agent B tries to work in an area Agent A has claimed:

```bash
# Agent B declares intent on the same file
$ wit declare --description "Fixing auth bug" --files src/api.ts

# Response includes conflict warning:
# {
#   "intentId": "abc-123",
#   "conflicts": {
#     "hasConflicts": true,
#     "items": [{
#       "type": "INTENT_OVERLAP",
#       "message": "Agent A has active intent on src/api.ts"
#     }]
#   }
# }
```

Agent B sees the warning, checks what Agent A is doing, and chooses to work on a different part of the codebase.

## Claude Code Plugin

Wit ships as a Claude Code plugin. Once installed, agents automatically declare intents and lock symbols before editing — no manual configuration.

**Step 1:** Add the Wit marketplace (one-time)
```
/plugin marketplace add amaar-mc/wit
```

**Step 2:** Install the plugin
```
/plugin install wit@amaar-mc-wit
```

**Step 3:** Make sure the CLI is installed (see [Install the CLI](#install-the-cli) above)

**Step 4:** Initialize Wit in your project
```bash
wit init
```

That's it. Every Claude Code instance in the project now coordinates automatically.

**What the plugin provides:**

- **`wit:coordinate` skill** — Instructs agents to declare intents and acquire locks before editing code. Activates automatically when `.wit/` exists.
- **Session hook** — On session start, loads current coordination state so agents immediately see what other agents are working on.

**Without Claude Code:** Wit works with any AI agent that can run shell commands. Add instructions to your agent's system prompt to call `wit declare`, `wit lock`, `wit status`, and `wit release`. See the [Protocol Specification](#protocol-specification) for the raw JSON-RPC API.

## Commands

| Command | What it does |
|---------|-------------|
| `wit init` | Create `.wit/`, start daemon, generate session ID |
| `wit status` | Show all active intents, locks, contracts, and conflicts |
| `wit declare` | Announce intent to work on files/symbols |
| `wit lock` | Acquire a semantic lock on a specific symbol |
| `wit release` | Release a held lock |
| `wit watch` | Live dashboard of coordination state |
| `wit hook install` | Install git hooks for contract enforcement and intent tracking |

All commands support `--json` for machine-readable output.

## Semantic Locking

Wit doesn't lock files — it locks **symbols**. A symbol is a function, class, type, or export identified by its path:

```
src/auth.ts:validateToken      # a function
src/models.ts:User             # a type/class
src/utils.py:calculate_score   # a Python function
src/utils.py:RateLimiter       # a Python class
```

Wit uses [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) WASM grammars to parse your code and identify symbol boundaries — the exact byte range of each function, class, and type. Two agents can safely work on different functions in the same file.

**Supported languages:** TypeScript, JavaScript, Python.

## Conflict Detection

When an agent declares an intent, Wit runs three checks:

| Check | What it catches |
|-------|----------------|
| **Intent Overlap** | Two agents targeting the same code region |
| **Lock Intersection** | Intent targets a symbol locked by another agent |
| **Dependency Chain** | Intent targets a caller of a locked symbol |

All conflicts are **warnings**. The intent still succeeds. The agent decides what to do.

## Contracts

Agents can agree on function signatures. Once accepted, a git pre-commit hook enforces the contract — commits that change the agreed signature are blocked.

```bash
# Install enforcement hooks
wit hook install

# Now if an accepted contract's signature changes, the commit is rejected
git commit -m "changed params"
# ERROR: Contract violation — src/auth.ts:validateToken signature changed
```

Contracts are propose/accept/reject. No counter-proposals in v1.

## Intent-to-Commit Tracking

`wit hook install` also installs a `prepare-commit-msg` hook. Active intents are linked to commits via git trailers:

```
feat: add rate limiting

Wit-Intent: abc-123-def-456
```

## Architecture

- **Daemon**: Bun process, Hono HTTP server, Unix domain socket
- **Storage**: SQLite with WAL mode for concurrent agent access
- **Parsing**: Tree-sitter WASM grammars (zero native dependencies, no build step)
- **CLI**: Clipanion, auto-starts daemon on first use
- **Protocol**: JSON-RPC 2.0 with `witVersion` field for version negotiation

## Protocol Specification

Wit exposes 12 JSON-RPC methods for agent coordination. Full spec in two formats:

- **[`docs/PROTOCOL.md`](docs/PROTOCOL.md)** — Human-readable with request/response examples for every method
- **[`docs/openrpc.json`](docs/openrpc.json)** — Machine-readable [OpenRPC 1.4.0](https://spec.open-rpc.org/) schema

Any AI coding tool that can POST JSON to a Unix socket or run a shell command can participate in the coordination protocol. Build your own integration using the spec.

## `.wit/` Directory

| File | Purpose |
|------|---------|
| `daemon.sock` | Unix domain socket for JSON-RPC communication |
| `daemon.pid` | Daemon PID for lifecycle management and crash recovery |
| `state.db` | SQLite database with WAL mode for concurrent access |
| `session.id` | Stable session identifier for agent tracking |

Add `.wit/` to your `.gitignore`.

## Supported Languages

Wit uses Tree-sitter WASM grammars to parse source code at the AST level. Currently supported:

- **TypeScript / JavaScript** (functions, arrow functions, methods, types, interfaces, classes)
- **Python** (functions, classes)

Adding a new language is straightforward. See [issue #1](https://github.com/amaar-mc/wit/issues/1) (Go), [#2](https://github.com/amaar-mc/wit/issues/2) (Rust), or [#4](https://github.com/amaar-mc/wit/issues/4) (Java/Kotlin) for examples of what's involved.

## Limitations (v1)

- Single machine only (no network coordination between remote agents)
- TypeScript/JavaScript and Python (more languages planned, architecture is extensible)
- CLI and API only (no GUI or dashboard beyond `wit watch`)
- Warnings only (locks and conflicts never block, except contract enforcement)
- Bun runtime required (standalone binary planned, see [#10](https://github.com/amaar-mc/wit/issues/10))

## Contributing

Wit is open source and contributions are welcome. Good places to start:

- [Good first issues](https://github.com/amaar-mc/wit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — language support, CLI improvements, documentation
- [Help wanted](https://github.com/amaar-mc/wit/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) — MCP server, Windows support, standalone binary

```bash
git clone https://github.com/amaar-mc/wit.git
cd wit
bun install
bun test
```

## License

MIT

---

<a href="https://github.com/amaar-mc/wit/stargazers">Star this repo</a> if you find it useful.

wit

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README