https://github.com/amaar-mc/wit
Agent coordination protocol — declare intents, lock symbols, detect conflicts before code is written
https://github.com/amaar-mc/wit
agents ai bun claude-code coordination developer-tools merge-conflicts tree-sitter typescript
Last synced: 29 days ago
JSON representation
Agent coordination protocol — declare intents, lock symbols, detect conflicts before code is written
- Host: GitHub
- URL: https://github.com/amaar-mc/wit
- Owner: amaar-mc
- License: mit
- Created: 2026-03-26T07:58:44.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-03-27T01:46:02.000Z (about 2 months ago)
- Last Synced: 2026-03-27T02:51:07.414Z (about 2 months ago)
- Topics: agents, ai, bun, claude-code, coordination, developer-tools, merge-conflicts, tree-sitter, typescript
- Language: TypeScript
- Homepage:
- Size: 2.11 MB
- Stars: 9
- Watchers: 1
- Forks: 2
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-agent-orchestrators - wit - Coordination protocol that locks specific functions (not files) via Tree-sitter AST parsing. Agents declare intents, acquire symbol level locks, and get conflict warnings before writing code. (Multi-Agent Swarms)
- awesome-cli-coding-agents - Wit - sitter AST parsing; agents declare intents, acquire symbol-level locks, and get conflict warnings before writing code. JSON-RPC daemon. MIT. (Harnesses & orchestration / Agent infrastructure)
README
Agent coordination protocol for shared codebases
Declare intents. Lock symbols. Detect conflicts. Before code is written.
---
**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
```
+-----------+ +-----------+ +-----------+
| Claude A | | Cursor B | | Copilot C |
+-----+-----+ +-----+-----+ +-----+-----+
| | |
| JSON-RPC over Unix socket |
| | |
+--------+-------+----------------+
|
+-----+------+
| Wit Daemon |
| |
| Hono HTTP |
| SQLite WAL |
| Tree-sitter|
+-----+------+
|
.wit/daemon.sock
.wit/state.db
```
- **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
---
Star this repo if you find it useful.