feat: peer-to-peer session sharing via Syncthing

[JayantDevkar]

What this adds

Share Claude Code sessions with your team — automatically, securely, with zero cloud infrastructure.

When you use Claude Code, your sessions live in ~/.claude/ on your machine. That's great for solo work, but the moment you have two machines or a teammate, everyone's sessions are invisible to each other. You lose context, duplicate work, and can't learn from how others use Claude.

This PR adds peer-to-peer session syncing powered by Syncthing. Sessions travel directly between machines over encrypted connections. No servers, no accounts, no third parties touching your data.

How it works

You use Claude Code → session saved locally → watcher packages it
    → Syncthing sends it to teammates → appears on their dashboard

1. Go to /sync — the setup wizard detects Syncthing and walks you through initialization
2. Create a team — give it a name, you become the leader
3. Invite teammates — they generate a join code, you paste it to add them
4. Share projects — pick which projects the team should sync
5. Accept subscriptions — each member controls what they send and receive
6. Sessions flow automatically — within seconds on LAN, minutes over the internet

Four core concepts

Concept	What it is
Member	A person + machine combo (e.g., jayant.macbook). Same person on two machines = two members.
Team	A group of members who can see each other's sessions. Teams are just access control — they don't store data.
Project	A git repository shared with a team, identified by its git remote (e.g., org/repo). You choose what to share.
Subscription	How you receive a shared project. Accept, pause, decline, or change direction (send-only, receive-only, both).

What you can do

• Create and manage teams from the /team page — add members via join codes, share projects, view activity
• Fine-grained subscriptions — accept, pause, resume, or decline any project. Choose sync direction per project.
• See teammate sessions — browse their conversations, tool usage, and token costs on your dashboard
• Multi-team support — be in different teams with different people, sharing different projects
• Automatic reconciliation — a background timer keeps everything in sync (member discovery, device pairing, folder management)
• Secure by default — TLS 1.3, mutual certificate auth, only paired devices can connect

What gets synced (and what doesn't)

Synced: session conversations, tool usage, token stats, subagent activity, session metadata

Never synced: your source code, secrets, .env files, anything outside ~/.claude/projects/, anything from projects you haven't shared

---

Architecture

The sync system is built in clean layers:

Domain Models (Team, Member, SharedProject, Subscription, SyncEvent)
    ↓
Repositories (SQLite persistence, UPSERT, FK cascades)
    ↓
Services (TeamService, ProjectService, ReconciliationService, MetadataService)
    ↓
Syncthing Abstraction (SyncthingClient → DeviceManager, FolderManager)
    ↓
FastAPI Routers (5 thin routers, dependency injection)
    ↓
SvelteKit Frontend (team pages, subscription management, setup wizard)

Domain-driven design: frozen Pydantic models with explicit state machines. Teams are active or dissolved. Members are added, active, or removed. Subscriptions are offered, accepted, paused, or declined. Invalid transitions raise errors.

3-phase reconciliation: runs every 60 seconds in the background

1. Metadata — read peer state files, detect removals, discover new members and projects
2. Mesh pair — ensure all active team members are paired in Syncthing
3. Device lists — compute who should receive each project folder, apply declaratively

---

What's in the PR

Backend — api/

Layer	Files	What it does
Domain models	api/domain/ (5 files)	Team, Member, SharedProject, Subscription, SyncEvent — frozen Pydantic models with state machines
Schema	api/db/schema.py	v19 migration — 6 tables with FKs, cascades, CHECK constraints
Repositories	api/repositories/ (5 files)	SQLite CRUD with UPSERT, parameterized queries
Syncthing layer	api/services/syncthing/ (3 files)	Async HTTP client, DeviceManager, FolderManager
Sync services	api/services/sync/ (5 files)	Pairing, metadata, team lifecycle, project sharing, reconciliation
Routers	api/routers/sync_*.py (5 files)	Teams, projects, subscriptions, pending devices/folders, system
WatcherManager	api/services/watcher_manager.py	Background timer driving reconciliation + session packaging

Frontend — frontend/

Area	What changed
/sync page	Setup wizard with Syncthing detection and initialization
/team page	Team listing with status badges and member counts
/team/[name]	5-tab detail: Overview, Members, Projects (with subscription management), Activity, Settings
Types	api-types.ts updated with SyncTeam, SyncTeamMember, SyncSubscription, SyncEvent
Components	TeamCard, TeamMemberCard, TeamProjectsTab (accept/pause/decline + direction picker), TeamActivityFeed

CLI — cli/karma/

• Session packager, file watcher, Syncthing client wrapper
• Config management (sync-config.json)
• Worktree discovery for Claude Desktop sessions

Documentation — docs/about/

• Syncing Sessions — full user guide
• API Reference — 30+ sync endpoints documented
• Quick Start — updated setup instructions

---

Numbers

• 286 commits across the full development arc (v1 → v2 → v3 → v4 domain rewrite)
• 298 files changed — +65,615 / -2,037 lines
• 295 sync v4 tests — domain models, repositories, services, E2E, router tests
• 0 frontend build errors, 7 pre-existing warnings
• 4-agent parallel code review caught 6 critical + 11 important issues, all fixed

Test plan

• All sync v4 tests pass (295 tests)
• Frontend builds cleanly (svelte-check — 0 errors)
• Code review: domain, services, routers, security — all critical issues resolved
• Documentation updated for v4 concepts
• Manual test: full create → join → share → accept → sync flow between two machines
• Manual test: subscription pause/resume/decline lifecycle
• Manual test: team dissolve + cleanup verification

🤖 Generated with Claude Code