{"id":48565414,"url":"https://github.com/amaar-mc/wit","last_synced_at":"2026-04-23T12:00:58.360Z","repository":{"id":346984580,"uuid":"1192432103","full_name":"amaar-mc/wit","owner":"amaar-mc","description":"Agent coordination protocol — declare intents, lock symbols, detect conflicts before code is written","archived":false,"fork":false,"pushed_at":"2026-03-27T01:46:02.000Z","size":2214,"stargazers_count":9,"open_issues_count":10,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-27T02:51:07.414Z","etag":null,"topics":["agents","ai","bun","claude-code","coordination","developer-tools","merge-conflicts","tree-sitter","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amaar-mc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-26T07:58:44.000Z","updated_at":"2026-03-27T01:46:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amaar-mc/wit","commit_stats":null,"previous_names":["amaar-mc/wit"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/amaar-mc/wit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amaar-mc%2Fwit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amaar-mc%2Fwit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amaar-mc%2Fwit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amaar-mc%2Fwit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amaar-mc","download_url":"https://codeload.github.com/amaar-mc/wit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amaar-mc%2Fwit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32179387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T11:42:27.955Z","status":"ssl_error","status_checked_at":"2026-04-23T11:42:18.877Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","bun","claude-code","coordination","developer-tools","merge-conflicts","tree-sitter","typescript"],"created_at":"2026-04-08T13:00:22.272Z","updated_at":"2026-04-23T12:00:58.354Z","avatar_url":"https://github.com/amaar-mc.png","language":"TypeScript","funding_links":[],"categories":["Multi-Agent Swarms","Harnesses \u0026 orchestration"],"sub_categories":["Agent infrastructure"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" alt=\"wit\" width=\"400\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAgent coordination protocol for shared codebases\u003c/strong\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Declare intents. Lock symbols. Detect conflicts. Before code is written.\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/amaar-mc/wit/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/amaar-mc/wit/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/wit-protocol\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/wit-protocol\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/amaar-mc/wit/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/amaar-mc/wit\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/amaar-mc/wit/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/amaar-mc/wit?style=social\" alt=\"Stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"demo.gif\" alt=\"Wit demo — two agents, same file, LOCK_CONFLICT\" width=\"600\" /\u003e\n\u003c/p\u003e\n\n**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.\n\nThe name comes from the word itself: the intelligence to coordinate before colliding. It also stands for **W**orkspace **I**ntent **T**racker.\n\n## The Problem\n\nYou 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.\n\nGit detects conflicts **after** they happen. Wit prevents them **before** code is written.\n\n## How It Works\n\nWit runs a lightweight daemon in the background. Agents communicate with it over a Unix socket using JSON-RPC. The daemon tracks four things:\n\n| Primitive | What it does | Example |\n|-----------|-------------|---------|\n| **Intents** | Agent announces planned work scope | \"I'm refactoring the auth module\" |\n| **Locks** | Agent reserves a specific function/type/class | Lock `src/auth.ts:validateToken` |\n| **Conflicts** | Daemon warns when intents or locks overlap | \"Agent B also declared intent on auth.ts\" |\n| **Contracts** | Agents agree on function signatures | \"validateToken accepts string, returns boolean\" |\n\nIntents 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.\n\n## Quick Start\n\n### Prerequisites\n\nWit 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:\n\n```bash\ncurl -fsSL https://bun.sh/install | bash\n```\n\n### Install the CLI\n\n**From npm:**\n```bash\nbun install -g wit-protocol\n```\n\n**From source:**\n```bash\ngit clone https://github.com/amaar-mc/wit.git\ncd wit\nbun install\nbun link\n```\n\nAfter either method, the `wit` command is available globally.\n\n### Initialize in your repo\n\n```bash\ncd your-project\nwit init\n```\n\nThis 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.\n\nEvery 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.\n\n### Basic workflow\n\n```bash\n# See what's happening\nwit status\n\n# Declare intent before working\nwit declare --description \"Adding rate limiting to API\" --files src/api.ts --files src/middleware.ts\n\n# Lock a specific function you're about to modify\nwit lock --symbol \"src/api.ts:handleRequest\"\n\n# Check status — your intent and lock are visible to all agents\nwit status\n\n# Release when done\nwit release --symbol \"src/api.ts:handleRequest\"\n\n# Watch live updates (like htop for coordination)\nwit watch\n```\n\n### What agents see\n\nWhen Agent B tries to work in an area Agent A has claimed:\n\n```bash\n# Agent B declares intent on the same file\n$ wit declare --description \"Fixing auth bug\" --files src/api.ts\n\n# Response includes conflict warning:\n# {\n#   \"intentId\": \"abc-123\",\n#   \"conflicts\": {\n#     \"hasConflicts\": true,\n#     \"items\": [{\n#       \"type\": \"INTENT_OVERLAP\",\n#       \"message\": \"Agent A has active intent on src/api.ts\"\n#     }]\n#   }\n# }\n```\n\nAgent B sees the warning, checks what Agent A is doing, and chooses to work on a different part of the codebase.\n\n## Claude Code Plugin\n\nWit ships as a Claude Code plugin. Once installed, agents automatically declare intents and lock symbols before editing — no manual configuration.\n\n**Step 1:** Add the Wit marketplace (one-time)\n```\n/plugin marketplace add amaar-mc/wit\n```\n\n**Step 2:** Install the plugin\n```\n/plugin install wit@amaar-mc-wit\n```\n\n**Step 3:** Make sure the CLI is installed (see [Install the CLI](#install-the-cli) above)\n\n**Step 4:** Initialize Wit in your project\n```bash\nwit init\n```\n\nThat's it. Every Claude Code instance in the project now coordinates automatically.\n\n**What the plugin provides:**\n\n- **`wit:coordinate` skill** — Instructs agents to declare intents and acquire locks before editing code. Activates automatically when `.wit/` exists.\n- **Session hook** — On session start, loads current coordination state so agents immediately see what other agents are working on.\n\n**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.\n\n## Commands\n\n| Command | What it does |\n|---------|-------------|\n| `wit init` | Create `.wit/`, start daemon, generate session ID |\n| `wit status` | Show all active intents, locks, contracts, and conflicts |\n| `wit declare` | Announce intent to work on files/symbols |\n| `wit lock` | Acquire a semantic lock on a specific symbol |\n| `wit release` | Release a held lock |\n| `wit watch` | Live dashboard of coordination state |\n| `wit hook install` | Install git hooks for contract enforcement and intent tracking |\n\nAll commands support `--json` for machine-readable output.\n\n## Semantic Locking\n\nWit doesn't lock files — it locks **symbols**. A symbol is a function, class, type, or export identified by its path:\n\n```\nsrc/auth.ts:validateToken      # a function\nsrc/models.ts:User             # a type/class\nsrc/utils.py:calculate_score   # a Python function\nsrc/utils.py:RateLimiter       # a Python class\n```\n\nWit 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.\n\n**Supported languages:** TypeScript, JavaScript, Python.\n\n## Conflict Detection\n\nWhen an agent declares an intent, Wit runs three checks:\n\n| Check | What it catches |\n|-------|----------------|\n| **Intent Overlap** | Two agents targeting the same code region |\n| **Lock Intersection** | Intent targets a symbol locked by another agent |\n| **Dependency Chain** | Intent targets a caller of a locked symbol |\n\nAll conflicts are **warnings**. The intent still succeeds. The agent decides what to do.\n\n## Contracts\n\nAgents can agree on function signatures. Once accepted, a git pre-commit hook enforces the contract — commits that change the agreed signature are blocked.\n\n```bash\n# Install enforcement hooks\nwit hook install\n\n# Now if an accepted contract's signature changes, the commit is rejected\ngit commit -m \"changed params\"\n# ERROR: Contract violation — src/auth.ts:validateToken signature changed\n```\n\nContracts are propose/accept/reject. No counter-proposals in v1.\n\n## Intent-to-Commit Tracking\n\n`wit hook install` also installs a `prepare-commit-msg` hook. Active intents are linked to commits via git trailers:\n\n```\nfeat: add rate limiting\n\nWit-Intent: abc-123-def-456\n```\n\n## Architecture\n\n```\n+-----------+    +-----------+    +-----------+\n| Claude A  |    | Cursor B  |    | Copilot C |\n+-----+-----+    +-----+-----+    +-----+-----+\n      |                |                |\n      |   JSON-RPC over Unix socket    |\n      |                |                |\n      +--------+-------+----------------+\n               |\n         +-----+------+\n         | Wit Daemon  |\n         |             |\n         |  Hono HTTP  |\n         |  SQLite WAL |\n         |  Tree-sitter|\n         +-----+------+\n               |\n         .wit/daemon.sock\n         .wit/state.db\n```\n\n- **Daemon**: Bun process, Hono HTTP server, Unix domain socket\n- **Storage**: SQLite with WAL mode for concurrent agent access\n- **Parsing**: Tree-sitter WASM grammars (zero native dependencies, no build step)\n- **CLI**: Clipanion, auto-starts daemon on first use\n- **Protocol**: JSON-RPC 2.0 with `witVersion` field for version negotiation\n\n## Protocol Specification\n\nWit exposes 12 JSON-RPC methods for agent coordination. Full spec in two formats:\n\n- **[`docs/PROTOCOL.md`](docs/PROTOCOL.md)** — Human-readable with request/response examples for every method\n- **[`docs/openrpc.json`](docs/openrpc.json)** — Machine-readable [OpenRPC 1.4.0](https://spec.open-rpc.org/) schema\n\nAny 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.\n\n## `.wit/` Directory\n\n| File | Purpose |\n|------|---------|\n| `daemon.sock` | Unix domain socket for JSON-RPC communication |\n| `daemon.pid` | Daemon PID for lifecycle management and crash recovery |\n| `state.db` | SQLite database with WAL mode for concurrent access |\n| `session.id` | Stable session identifier for agent tracking |\n\nAdd `.wit/` to your `.gitignore`.\n\n## Supported Languages\n\nWit uses Tree-sitter WASM grammars to parse source code at the AST level. Currently supported:\n\n- **TypeScript / JavaScript** (functions, arrow functions, methods, types, interfaces, classes)\n- **Python** (functions, classes)\n\nAdding 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.\n\n## Limitations (v1)\n\n- Single machine only (no network coordination between remote agents)\n- TypeScript/JavaScript and Python (more languages planned, architecture is extensible)\n- CLI and API only (no GUI or dashboard beyond `wit watch`)\n- Warnings only (locks and conflicts never block, except contract enforcement)\n- Bun runtime required (standalone binary planned, see [#10](https://github.com/amaar-mc/wit/issues/10))\n\n## Contributing\n\nWit is open source and contributions are welcome. Good places to start:\n\n- [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\n- [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\n\n```bash\ngit clone https://github.com/amaar-mc/wit.git\ncd wit\nbun install\nbun test\n```\n\n## License\n\nMIT\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/amaar-mc/wit/stargazers\"\u003eStar this repo\u003c/a\u003e if you find it useful.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famaar-mc%2Fwit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famaar-mc%2Fwit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famaar-mc%2Fwit/lists"}