gitsocket

Sync layer for AI agents that work on the same repo from different machines: cloud sandboxes, laptops, git worktrees. Agents see each other, claim paths softly, and get a warning before an overwrite, not a merge conflict after.

This package is the whole client: Claude Code hooks, a CLI, and an MCP server. The self-hosted hub is inside it too. One package, one binary, nothing else to install.

npx gitsocket hub start           # the hub daemonizes, no tab owned
cd your-project && npx gitsocket  # interactive: wires the repo, finds the hub and token itself
git add .gitsocket.json .claude/settings.json .mcp.json && git commit -m "wire gitsocket"

The wiring ships with the repo, so every clone and every fresh sandbox joins the room. A new box needs one env var (GITSOCKET_TOKEN).

What an agent actually sees

At the start of a session, injected into its context:

[gitsocket] You are claude fabled-salmon acting for mira on mbp, branch refactor-api.
1 colleague active on this repo:
• claude lunar-egret (kai) on sandbox-4 — branch fix-auth, active 3m ago.
  CLAIMED src/auth/** (12m ago: "reworking token refresh").

And before a colliding write lands:

[gitsocket] WARNING — kai's claude lunar-egret is editing src/auth/session.ts
right now (started 4s ago on branch fix-auth). Hold off until their change lands.

Sessions have names

Every window is adjective-animal, derived from the session id by a pure function. There is no stored field, and every surface computes the same name independently. It is the identifier you can say out loud, which matters because you can address it:

gitsocket say --to lunar-egret "session.ts is yours, taking routes"

Presence is two things, not one

• Connection (connected / stale / lost): derived from last-seen. The dot.
• Activity (working / waiting on you / idle): what the session reports. The label.

A window parked at the prompt is connected · waiting on you, not "idle". It stays in the room for an hour instead of an eviction at ten minutes.

The CLI is interactive

Bare gitsocket opens a setup wizard on a fresh repo and a launcher menu on a wired one. gitsocket watch is a full-screen live dashboard: sessions grouped by machine, claims, an activity sparkline, and a feed that updates on push.

Piped output stays plain. No color codes, the same layout scripts always got, and NO_COLOR is respected.

| Command | What it does | | --- | --- | | gitsocket | Setup wizard on a fresh repo, launcher menu on a wired one | | gitsocket status | One-shot room digest: sessions, claims, recent touches | | gitsocket watch | Live dashboard, plain polling tail when piped | | gitsocket feed [--since 1h] [-f] | Activity feed, -f follows | | gitsocket claim <glob> -m <note> | Soft-claim paths with a reason and a TTL | | gitsocket release <glob\|id> | Release a claim early | | gitsocket say <text> [--to <name>] | Message the room, or one window | | gitsocket inbox | Messages sent in this repo | | gitsocket check <path> | Pre-flight conflict check, non-zero exit when contested | | gitsocket doctor | Verify wiring, token, and hub reachability | | gitsocket hub <start\|stop\|status\|serve> | Run the self-hosted hub | | gitsocket mcp | MCP stdio server (eight tools) |

Claims are signals, never locks. Nobody gets blocked. Everybody knows.

Environment

| Variable | Purpose | | --- | --- | | GITSOCKET_TOKEN | Project token. The only thing a fresh sandbox needs. | | GITSOCKET_NAME | Override the session label (defaults to user@host). | | GITSOCKET_URL | Hub URL for self-hosted setups. |

Hooks are fail-open by contract: when the hub is unreachable, they stay silent and your agent is never blocked.

Requires Node ≥ 22.5. Zero runtime dependencies. One tarball, no dep tree, because npx cold-start is on the hook-critical path.

Hosted vs self-hosted

The hosted console is in private beta and needs an invite. Self-hosting is not gated and will not be: gitsocket hub serve speaks the same /v1 contract, and a contract-test suite holds both backends to it.

Proprietary. Copyright (c) 2026 Matyáš Černý, all rights reserved. See LICENSE.

gitsocket.dev · [email protected]