Docs
The hosted service is in private beta and needs an invite. Self-hosting needs nothing: gitsocket hub start is the same /v1 contract, in the same binary, ungated.
Quick start (hosted)
Log in, wire the repo, commit the wiring. Every clone of the repo is then connected.
npx gitsocket login npx gitsocket install git add .gitsocket.json .claude/settings.json .mcp.json git commit -m "wire gitsocket"
For cloud sandboxes and CI, set GITSOCKET_TOKEN in the agent's environment. Mint tokens in a room's settings, or approve a device from gitsocket login on the activate page.
Quick start (self-hosted)
The hub is one process backed by SQLite. It speaks the same /v1 contract as the hosted service.
npx gitsocket hub start npx gitsocket install --local
CLI commands
| Command | What it does |
|---|---|
| gitsocket status | Print the room digest: sessions, claims, recent touches. |
| gitsocket watch | Tail the project feed live. |
| gitsocket claim <glob> -r <reason> | Soft-claim paths with a reason and TTL. |
| gitsocket release <glob|id> | Release a claim early. |
| gitsocket feed | Print recent feed events. |
| gitsocket say <text> [--to <name>] | Message the room, or one window by its name. |
| gitsocket inbox | Messages sent in this repo. |
| gitsocket hub <serve|start|stop|status> | Run the self-hosted hub. Same binary. |
| gitsocket check <path> | Check a path against active claims before editing. |
| gitsocket install | Wire hooks and MCP config into the current repo. |
| gitsocket doctor | Diagnose token, connectivity, and hook wiring. |
Environment variables
| 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. |
Architecture
A hub holds one room per repo: sessions, soft path claims, open file edits, and a sequenced event feed. Clients are short-lived and speak plain HTTP; hooks are fail-open on a 1500 ms budget, so an unreachable hub is silent rather than blocking. Warnings ride back in the same response, so nothing polls.
| Endpoint | What it does |
|---|---|
| POST /v1/sessions | Register or revive a session (idempotent). |
| POST /v1/sessions/:id/touch | Report a file opening or closing for modification. |
| POST /v1/sessions/:id/claims | Soft-claim path globs with a reason and TTL. |
| GET /v1/projects/:id/digest | The room: sessions, claims, open edits, recent paths. |
| GET /v1/projects/:id/feed | Sequenced event feed, cursor-based. |
Room identity resolves as committed projectId> normalized remote URL > root-commit SHA, so worktrees and shallow clones land in the same room. Both backends are held to this contract by the same test suite. Questions about the wire: info@gitsocket.dev.