Safe Parallel Coding
Safe Parallel Coding lets several humans and AI agents work in the same repository without guessing who owns a file, route, schema, deployment, or release surface. Snipara stores the shared coordination state in the hosted project backend, then exposes it through companion commands, MCP tools, dashboard views, Git hooks, and GitHub checks.
Product boundary
Local state can help one machine coordinate itself. Hosted collaboration is the source of truth when multiple people, agents, terminals, CI jobs, and GitHub checks need the same presence, leases, conflict alarms, and expiry behavior.
The coordination loop
Start a session, claim the resources you are actively touching, run the guard before code moves, then heartbeat or release leases as the work changes.
snipara-companion collaboration start --summary "Refactor billing invite flow" --files apps/web/src/lib/billing.tssnipara-companion collaboration claim --mode EXCLUSIVE --ttl-seconds 600 --resource FILE:apps/web/src/lib/billing.tssnipara-companion collaboration guard --profile pre-commit --enforcesnipara-companion collaboration release --reason "Billing refactor done"Surfaces
| Surface | What it does | Command |
|---|---|---|
| Presence | Publish who is working, on which branch, and on which files or resources. | snipara-companion collaboration start |
| Resource leases | Claim files, routes, symbols, schemas, packages, docs, deploys, or custom resources. | snipara-companion collaboration claim |
| Guard checks | Evaluate overlap before edits, commits, pushes, handoffs, migrations, or releases. | snipara-companion collaboration guard --enforce |
| Live status | Read active sessions, leases, recent guard events, and the last local guard result. | snipara-companion collaboration status |
Lease modes and TTL
Advisory modes can be long-lived when the team wants soft visibility. Blocking modes are time-bound so a crashed terminal or abandoned agent cannot hold the repository indefinitely.
| Mode | Guard effect | TTL |
|---|---|---|
| WATCH | Informational visibility. | 300s heartbeat default |
| ADVISORY | Warn other agents without blocking by default. | Optional direct claim; 4h explicit for FULL/orchestrate workflows |
| REQUIRES_ACK | Require acknowledgement before continuing. | Optional |
| EXCLUSIVE | Block unsafe overlap on the claimed resource. | 300s when no explicit TTL is provided |
| HARD_BLOCK | Stop work until release, override, or expiry. | 300s when no explicit TTL is provided |
Enforcement details
TTL range
Explicit lease TTLs must be 30 to 86,400 seconds.
Heartbeat renewal
Watch heartbeats default to 300 seconds; a heartbeat extends the lease expiry using the current TTL window.
Blocking claim defaults
Direct EXCLUSIVE and HARD_BLOCK claims, including hook claims, default to 300 seconds when no explicit TTL is supplied.
Workflow claims
FULL and orchestrate workflows automatically create ADVISORY claims with an explicit 4-hour TTL.
Overrides and expiry
An explicit TTL overrides these defaults. When a lease expires, it is no longer an active blocker; claim the resource again if work continues.
Expired leases
Expired active leases are surfaced as expired and stop acting as active blockers.
Hard blocks
Only owners, admins, internal automation, or API key automation can create HARD_BLOCK leases.
GitHub checks
Collaboration checks can publish only to the project's configured GitHub repository.
Payload limits
Requests limit file lists, resource lists, repository-relative paths, and JSON metadata size and depth.
Blocking hooks and GitHub checks
Companion can install managed pre-commit and pre-push hooks that call the hosted collaboration guard with --enforce. Production deployment and schema or package release workflows can run stricter profiles before code leaves the local worktree.
After inspecting a known review-only finding, pass a one-operation acknowledgement through the hook with SNIPARA_COLLABORATION_GUARD_ACK_REVIEW_ONLY=1 git commit. The hook immediately re-runs without the flag so the acknowledgement is consumed; leases, active-session conflicts, required acknowledgements, and blocked results still fail.
For GitHub, Snipara publishes a check named Snipara Collaboration Guard against the configured project repository. Clear or watch-only results pass; review, acknowledgement, or blocked results surface as required action or failure.
Emergency bypass is explicit: set SNIPARA_COLLABORATION_GUARD=0 only when a human intentionally accepts the risk.