{"_id":"@bytlabs/ccrelay","_rev":"2-918db92d178e823e7394bd6e2b76c89f","name":"@bytlabs/ccrelay","dist-tags":{"latest":"0.1.5"},"versions":{"0.1.4":{"name":"@bytlabs/ccrelay","version":"0.1.4","keywords":["claude","claude-code","ai","collaboration","session","self-hosted"],"license":"Apache-2.0","_id":"@bytlabs/ccrelay@0.1.4","maintainers":[{"name":"xlncbasit","email":"xlncbasit@gmail.com"}],"homepage":"https://github.com/xlncbasit/claude-shared-session","bugs":{"url":"https://github.com/xlncbasit/claude-shared-session/issues"},"os":["linux","darwin"],"bin":{"ccrelay":"run.js"},"dist":{"shasum":"2025a4c88969934abb1d88b0e79eda9ac1ef5f3d","tarball":"https://registry.npmjs.org/@bytlabs/ccrelay/-/ccrelay-0.1.4.tgz","fileCount":6,"integrity":"sha512-zYRsY77fs2q3jzGAJjmBnUh7sZQWdiTegcFosVh7nuKdy0T745dFMnU6HjULuBj/yKUqCRIZbGQuo+kZraTakA==","signatures":[{"sig":"MEUCICraHBb51JBDEEI57oJhru0T6hBhlzYApJRjYdXgjPmkAiEA7DGWBB+oM4eqFvH+SK7av3iMHzRbgWs0LnpoOzlfZXU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44872090},"engines":{"node":">=16"},"gitHead":"746b2372f296c2445110d0c11034b48d16305c40","_npmUser":{"name":"xlncbasit","email":"xlncbasit@gmail.com"},"repository":{"url":"git+https://github.com/xlncbasit/claude-shared-session.git","type":"git"},"_npmVersion":"11.12.1","description":"Collaboration Layer for Claude Code — self-host on your own infra","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ccrelay_0.1.4_1782465493618_0.5025063410242858","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@bytlabs/ccrelay","version":"0.1.5","description":"Collaboration layer for Claude Code — share sessions across machines in real time","keywords":["claude","claude-code","ai","collaboration","session","self-hosted","pair-programming"],"homepage":"https://www.bytlabs.fun/ccrelay","repository":{"type":"git","url":"git+https://github.com/xlncbasit/claude-shared-session.git"},"license":"AGPL-3.0","bin":{"ccrelay":"run.js"},"os":["linux","darwin"],"engines":{"node":">=16"},"gitHead":"4fd8f1e820206b4b059eeade084f838d5c9e5ab4","_id":"@bytlabs/ccrelay@0.1.5","bugs":{"url":"https://github.com/xlncbasit/claude-shared-session/issues"},"_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-lz4RQNEt7GSI5EbgQIlSUa4TTBRJc7rKbSHuuZyvTpreAluLcWRcoETpP0rTp6vhTUrHSfcBSA0bCRngSYyb7A==","shasum":"f12019178eed4f408e89806d7dbc70c384c5e8b1","tarball":"https://registry.npmjs.org/@bytlabs/ccrelay/-/ccrelay-0.1.5.tgz","fileCount":7,"unpackedSize":44882520,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDUOTNQClqaZ2VH3yxK0iyPY1xm9b/Lq8j21nv6pWgCUAIgMXY+OOz1ZAoSxGVVIXL2Gn71DCOVliSAAw3rHaGhxEo="}]},"_npmUser":{"name":"xlncbasit","email":"xlncbasit@gmail.com"},"directories":{},"maintainers":[{"name":"xlncbasit","email":"xlncbasit@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ccrelay_0.1.5_1782888969162_0.2812352937557927"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-26T09:18:13.467Z","modified":"2026-07-01T06:56:09.679Z","0.1.4":"2026-06-26T09:18:13.989Z","0.1.5":"2026-07-01T06:56:09.536Z"},"bugs":{"url":"https://github.com/xlncbasit/claude-shared-session/issues"},"license":"AGPL-3.0","homepage":"https://www.bytlabs.fun/ccrelay","keywords":["claude","claude-code","ai","collaboration","session","self-hosted","pair-programming"],"repository":{"type":"git","url":"git+https://github.com/xlncbasit/claude-shared-session.git"},"description":"Collaboration layer for Claude Code — share sessions across machines in real time","maintainers":[{"name":"xlncbasit","email":"xlncbasit@gmail.com"}],"readme":"# CCRelay\n\nShare a Claude Code session across machines in real time.  \nOne engineer runs Claude — teammates attach, watch, queue prompts, and claim the session with one command. No screen-sharing. No context loss.\n\n![CCRelay handoff demo](demo.gif)\n\n**Free and open source · AGPL v3 · Self-host in 2 minutes**\n\n---\n\n> **A note from the developer**\n>\n> I built CCRelay for everyone who's using AI to build — especially the ones doing it for the\n> first time. The domain expert who finally has a way to turn their knowledge into software.\n> The founder who knows exactly what to build but is still learning how. Tools like Claude Code\n> are rewriting who gets to be a builder, and that's worth building for.\n>\n> CCRelay exists so that building with AI doesn't have to be a solo act. Bring in a friend,\n> a mentor, a collaborator — let them watch, suggest, and take the wheel without losing context.\n>\n> This is free. It will stay free. Build something.\n>\n> — Basit\n\n---\n\n## How it works\n\n```\nMachine A (owner)          CC Relay Server          Machine B (observer)\n  ccrelay start      ──►  PostgreSQL + SSE  ──►    ccrelay attach\n  Claude runs        ◄──  lease / heartbeat  ──►   ccrelay claim\n  hooks fire         ──►  event stream       ──►   stream in real-time\n```\n\n1. **Server** (`ccshared`) — Go HTTP server backed by PostgreSQL. Stores sessions, events, leases, and queued prompts. Pushes real-time updates via SSE and WebSocket.\n2. **Client CLI** (`ccrelay`) — runs on each developer machine. Connects to the server, starts a daemon that reads Claude Code's JSONL output, fires hook events, and manages the exclusive-executor lease.\n3. **Claude hooks** — installed into `~/.claude/settings.json`. The `PreToolUse` hook calls the local daemon; if this machine doesn't hold the lease, the hook blocks execution — only the lease-owner can run tools.\n\n**Lease system**: only one machine holds the execution lease at a time. Ownership transfers via `ccrelay claim` or `ccrelay handoff`.\n\n---\n\n## Quickstart — Docker Compose\n\nThe fastest path to a running server. Requires Docker and Docker Compose.\n\n```bash\ngit clone https://github.com/xlncbasit/claude-shared-session.git\ncd claude-shared-session\n\ncp .env.example .env\n# Set CCSHARED_SECRET to a long random string:\n# CCSHARED_SECRET=$(openssl rand -hex 32)\n\ndocker compose up -d\n```\n\nTest it:\n\n```bash\ncurl http://localhost:8080/health\n```\n\n### Install the CLI\n\n```bash\n# npm (recommended — handles platform detection automatically)\nnpm install -g @bytlabs/ccrelay\n\n# or curl installer (Linux / macOS)\ncurl -fsSL https://raw.githubusercontent.com/xlncbasit/claude-shared-session/main/scripts/install.sh | sh\n\n# or go install\ngo install github.com/xlncbasit/claude-shared-session/ccshare/cmd/ccshare@latest\n```\n\n### Connect a machine\n\n```bash\nexport CCSHARE_API_URL=http://your-server:8080\nexport CCSHARE_API_SECRET=<value of CCSHARED_SECRET>\n\n# Start a session (run from your project root)\nccrelay start\n\n# On another machine — attach and watch\nccrelay attach --session-id <id>\n```\n\n---\n\n## Quickstart — Bare Metal\n\n### 1. PostgreSQL\n\n```sql\nCREATE USER ccshared WITH PASSWORD 'changeme';\nCREATE DATABASE ccshared OWNER ccshared;\n```\n\n### 2. Server binary\n\nDownload a pre-built binary from [Releases](https://github.com/xlncbasit/claude-shared-session/releases) or build from source:\n\n```bash\ngit clone https://github.com/xlncbasit/claude-shared-session.git\ncd claude-shared-session\nCGO_ENABLED=0 go build -o /usr/local/bin/ccshared ./ccshared/cmd/ccshared\n```\n\n### 3. Environment\n\n```bash\ncp .env.example /etc/ccrelay.env\n# Edit /etc/ccrelay.env — set CCSHARED_DSN and CCSHARED_SECRET at minimum\n```\n\n### 4. Systemd unit\n\n```ini\n# /etc/systemd/system/ccshared.service\n[Unit]\nDescription=CC Relay Server\nAfter=network.target postgresql.service\n\n[Service]\nEnvironmentFile=/etc/ccrelay.env\nExecStart=/usr/local/bin/ccshared\nRestart=on-failure\nRestartSec=5\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsystemctl daemon-reload\nsystemctl enable --now ccshared\njournalctl -u ccshared -f\n```\n\nThe server auto-runs all database migrations on startup — no separate migration step needed.\n\n---\n\n## CLI reference\n\n```\nccrelay start                   Start a new session and daemon for this repo\nccrelay attach --session-id ID  Attach (read-only) to an existing session\nccrelay claim                   Claim the execution lease from another machine\nccrelay status                  Show session, lease, and connection status\nccrelay handoff [@user]         Hand off the session to a teammate\nccrelay queue <prompt>          Submit a prompt to the session owner's queue\nccrelay watch                   Tail the live event stream\nccrelay daemon start            Run the background daemon directly (for debugging)\nccrelay install-claude-commands Install /ccrelay slash commands into Claude Code\nccrelay login --token <token>   Save a JWT token (from the web UI or /auth/login)\n```\n\n---\n\n## Claude Code slash commands\n\nAfter `ccrelay install-claude-commands`, you can use these inside Claude Code:\n\n| Command | Action |\n|---|---|\n| `/ccrelay` | Start or resume a session |\n| `/ccrelay-status` | Show session status |\n| `/ccrelay-handoff [@user]` | Hand off to a teammate |\n| `/ccrelay-attach <id>` | Attach to an existing session |\n| `/ccrelay-login <token>` | Authenticate |\n\n---\n\n## Configuration reference\n\nAll configuration is via environment variables.\n\n### Required\n\n| Variable | Description |\n|---|---|\n| `CCSHARED_DSN` | PostgreSQL connection string |\n\n### Server\n\n| Variable | Default | Description |\n|---|---|---|\n| `CCSHARED_ADDR` | `:8080` | Listen address |\n| `CCSHARED_BASE_URL` | `http://localhost:8080` | Public URL (used for OAuth redirects) |\n\n### Auth\n\n| Variable | Description |\n|---|---|\n| `CCSHARED_SECRET` | Shared bearer token — all clients pass this. Good for private team deployments. |\n| `CCSHARED_JWT_SECRET` | Enable user registration and per-user JWT auth. Generate: `openssl rand -hex 32` |\n\nAt least one auth method should be set. If neither is set the server runs with no auth (local dev only).\n\n### GitHub OAuth (optional)\n\n| Variable | Description |\n|---|---|\n| `CCSHARED_GITHUB_CLIENT_ID` | GitHub OAuth App client ID |\n| `CCSHARED_GITHUB_CLIENT_SECRET` | GitHub OAuth App client secret |\n| `CCSHARED_GITHUB_REDIRECT_URL` | Callback URL (default: `$CCSHARED_BASE_URL/auth/github/callback`) |\n| `CCSHARED_GITHUB_ORG` | Restrict sign-ins to members of this GitHub org |\n\n### OIDC / SSO (optional)\n\n| Variable | Description |\n|---|---|\n| `CCSHARED_OIDC_ISSUER` | OIDC issuer URL (e.g. `https://accounts.google.com`) |\n| `CCSHARED_OIDC_CLIENT_ID` | OIDC client ID |\n| `CCSHARED_OIDC_CLIENT_SECRET` | OIDC client secret |\n| `CCSHARED_OIDC_REDIRECT_URL` | Callback URL (default: `$CCSHARED_BASE_URL/auth/sso/callback`) |\n\n### CLI (client side)\n\n| Variable | Default | Description |\n|---|---|---|\n| `CCSHARE_API_URL` | `http://localhost:8080` | CC Relay server URL |\n| `CCSHARE_API_SECRET` | — | Shared secret or JWT token |\n\n---\n\n## Architecture overview\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                      CC Relay Server                     │\n│                                                          │\n│  chi router ──► api handlers ──► service layer          │\n│                                  │                       │\n│  SSE /events/stream              ▼                       │\n│  WS  /ws           ◄──── hub (fanout) ◄── stores        │\n│                                  │                       │\n│                              PostgreSQL                  │\n└─────────────────────────────────────────────────────────┘\n        ▲                                        ▲\n        │  HTTPS / WSS                           │\n┌───────┴────────┐                    ┌──────────┴──────┐\n│  Machine A     │                    │  Machine B       │\n│                │                    │                  │\n│  ccrelay daemon│                    │  ccrelay attach  │\n│  ├─ hook server│                    │  └─ event stream │\n│  ├─ heartbeat  │                    │                  │\n│  └─ JSONL tail │                    │  ccrelay claim   │\n│                │                    │  └─ takes lease  │\n│  Claude Code   │                    │                  │\n│  └─ hooks ──►  │                    │  Claude Code     │\n│    lease check │                    │  └─ hooks blocked│\n└────────────────┘                    └──────────────────┘\n```\n\n---\n\n## Deployment checklist\n\nFor a production self-hosted instance:\n\n- [ ] PostgreSQL with persistent storage and regular backups\n- [ ] `CCSHARED_SECRET` or `CCSHARED_JWT_SECRET` set to a strong random value\n- [ ] TLS termination in front of the server (nginx, Caddy, Cloudflare Tunnel)\n- [ ] `CCSHARED_BASE_URL` set to your public HTTPS URL\n- [ ] Firewall: only expose port 8080 (or 443 after TLS) — PostgreSQL should not be public\n- [ ] Server runs as a non-root user with `Restart=on-failure`\n\n### Reverse proxy (Caddy example)\n\n```\nyour.domain.com {\n    reverse_proxy localhost:8080\n}\n```\n\n---\n\n## Building from source\n\n```bash\ngit clone https://github.com/xlncbasit/claude-shared-session.git\ncd claude-shared-session\n\n# Build server\ngo build -o ccshared ./ccshared/cmd/ccshared\n\n# Build CLI\ngo build -o ccrelay ./ccshare/cmd/ccshare\n\n# Run tests\ngo test ./...\n```\n\nRequires Go 1.22+.\n\n---\n\n## Contributing\n\nPull requests are welcome. For larger changes, open an issue first to discuss the approach.\n\n```bash\ngo test ./...\ngo vet ./...\n```\n\nPlease do not commit `.env` files or any credentials.\n\n---\n\n## License\n\nAGPL-3.0 — see [LICENSE](LICENSE).\n\nThe server and CLI are fully open source. Self-host freely.  \nIf you distribute a modified version as a network service, you must publish your source changes.\n","readmeFilename":"README.md"}