Documentation

Quickstart

Five minutes, one repository, no account. Strandline works locally first; the hosted service adds shared state across machines, durable merge workflows and landing through your merge queue.

# macOS / Linux
brew install strandline-dev/tap/strandline

# any platform; verifies the checksum (and signature, with cosign)
curl -fsSL https://github.com/strandline-dev/strandline/releases/latest/download/install.sh | sh

# the MCP server alone (`strandline-mcp`)
npm install -g @strandline-dev/mcp

git clone https://github.com/strandline-dev/strandline && cd strandline
make setup build                              # builds target/debug/strandline and the MCP server
cargo install --path crates/strandline-cli    # puts `strandline` on your PATH

cd your-repo
strandline init
git add .gitattributes .strandline && git commit -m "Set up Strandline"

  checks: strandline verify will run what it detects (`npm test --silent`); to change them, write
  .strandline/verify.toml and commit it

[[check]]
name = "typecheck"
run = "npx tsc -p ."

[tests]
all = "npm test --silent"

strandline install --agent claude-code     # or codex, cursor, copilot, generic

$ strandline verify agent-a agent-b
merged   agent-a
merged   agent-b
FAIL  tests  (562 ms)  npm test --silent
alone    agent-a passes
alone    agent-b passes

Strandline combined `agent-a` and `agent-b` on top of `main` and the result fails `tests`.
Each branch passes on its own, so the failure comes from combining them.

Failing check `tests` (`npm test --silent`):
    AssertionError [ERR_ASSERTION]: 220 == 120

The conflicting changes:
- `agent-b` added `invoice` (src/invoice.js), which calls `tax`; `agent-a` changed what
  `tax` in src/pricing.js does (its signature is unchanged): it was `return a * 0.2;`
  and is now `return a * 1.2;`.

strandline login --url https://strandline.example.com     # paste an API key (or, where SSO is enforced, a session)
strandline whoami

Concepts

Many agents (and people) change one repository at once. Strandline coordinates them while they work, merges what they produce, verifies the combination, repairs it when needed, and lands exactly what it verified.

The pieces

While agents work: coordination

• Agent. One working copy (typically a git worktree) doing one task. Identity: --agent <id>, else STRANDLINE_AGENT_ID, else the current branch name. An agent is active if seen in the last STRANDLINE_AGENT_TTL (default 2 h); every command it runs refreshes last_seen.
• Registration and scope. An agent registers its task and scope: the files and symbols predicted from its --task text plus explicit --scope paths. Scope is what makes the rest precise.
• Base. The revision an agent's work is compared against: --base <rev>, else the registered base, else git merge-base HEAD main (falling back to master, then HEAD).
• Index and hotspots. Strandline indexes symbols, imports and calls for TypeScript/JavaScript, Python, Go, Rust, Ruby and Java (tree-sitter). Files many others depend on are hotspots.
• Leases (claims). An exclusive, time-limited claim by one agent on a path (file or directory prefix), default TTL 30 min. Another active agent asking for it is refused and told who holds it and why. Expired or released leases are inert.
• Footprint. What an agent has changed relative to its base: changed files and changed symbols. Recomputed by contract publish and collisions.
• Contracts. A contract change is a change to a public interface in an agent's working tree relative to its base: an exported symbol added, removed or with a changed signature (functions, methods of exported classes, classes, types, interfaces, enums, exported variables), or a route added or removed. Agents publish them to a shared contract log so others learn about them before merging.
• Relevance. A change by agent A to symbol S in file F is relevant to agent B if F is among B's files of interest (the files it changed, its declared scope, and paths it holds live leases on), or one of those files imports F or calls S, or (routes) mentions the route path, or B's task mentions S. Only relevant changes are announced, over subscriptions/listen. Callers that already exist in the base are A's responsibility.
• Retirement. A contract change leaves the current set once it reaches the integration branch (main, else master): the publishing branch was merged, or main already has the same signature (squash merge, cherry-pick). Retired changes are never announced again; contract changes --retired lists them with the reason.
• Collisions and plans. strandline collisions shows whose changes or leases overlap with yours (severity symbol > file > lease > dependency); strandline plan forecasts collisions for a task list and suggests an order, splits and leases.

Locally, this state lives in the repository's git directory (one SQLite file shared by all worktrees, <git-common-dir>/strandline/state.sqlite, override STRANDLINE_STATE; WAL mode, safe for concurrent processes). Hosted, it lives in the service, keyed by the repository's root-commit SHA, so agents on different machines share it. Only metadata is sent.

Merge driver

strandline init makes Strandline git's merge driver. For each file:

1. Code: the structural engine (merging by syntax units) and the optional pinned Weave engine, in the order measured best for each language, each falling back to the other; then, when both sides only added imports or module declarations at the same place, both are kept. Every clean result must pass the guard (no lost lines, no duplicated or orphaned declarations, still parses); otherwise it is a conflict, never a silently wrong merge.
2. Manifests (package.json, Cargo.toml, go.mod, pyproject.toml, Gemfile, pom.xml, version catalogs) merge by key; lockfiles are regenerated by the package manager, never text-merged.
3. Line sets (.gitignore, .gitattributes, CODEOWNERS) merge as unions, with order-sensitive rules kept as conflicts; generated files you list in .strandline/merge.toml are regenerated, not merged.

The guard is also available on its own (strandline guard) to judge a merged file whichever tool produced it, and strandline merge-check checks a whole merge for stale references to a name one branch renamed.

Before it lands: verification

A clean merge is not a working one. strandline verify <branches…> builds the combination in a scratch worktree and runs the checks from .strandline/verify.toml:

• If it fails, each branch is run alone and so is the base, so the report can say whether the failure comes from combining them, from one branch, or was already there.
• The failure is explained in terms of the changes: who changed what the failing code depends on.
• Test selection runs only affected tests, using Nx, Turborepo, Bazel, Cargo/Go/npm/pnpm workspaces where present, else the import graph.
• Flaky tests are rerun, recorded and quarantinable; a flake is never reported as a conflict and never triggers a repair.
• Your code runs in a sandbox: containers with no network, a read-only root, resource and time limits, or a microVM.

When it fails: repair

strandline repair asks a provider (Claude, a command, or a scripted mock) for a fix to the combination. A fix is accepted only if it passes the guard (it may not weaken or delete tests, touch protected files including every file a check command runs, special-case tested values, or add network, process, eval or environment access) and then the full test suite. At most a few attempts; otherwise a human gets the evidence.

Landing

A merge attempt (from an agent's strandline_request_merge, a GitHub pull request or a GitLab merge request) runs as a durable workflow: it survives worker crashes and never verifies, repairs or lands twice. It lands through your queue (GitHub's merge queue, Mergify, Graphite, GitLab merge trains) or Strandline's own. Batches and repairs land through a batch PR of exactly the commit that was verified. The PR gets a signed receipt (what was combined, checked, repaired, and the digest of the result); each member PR gets a note linking to it.

Hosted service

• Workspaces, roles, keys. Owner, admin, member, agent; API keys with scopes (read, write, coordinate, merge, webhooks, admin); agent keys bound to one agent id.
• Isolation. Postgres row-level security on every tenant table; the service connects as a non-owner role.
• SSO. OIDC and SAML per workspace, with domain claims, just-in-time members and enforcement. An audit log of every privileged action and retention settings.
• Integrations. GitHub App, GitLab, outgoing signed webhooks, a GitHub Action and GitLab CI component (strandline ci verify), an OpenAPI description of the API.
• Billing. Landed, verified merges are metered; a free tier is enforced at admission.
• Operations. Metrics, dashboards, alerts, SLOs, Helm and Compose installs: Self-hosting.

Security model and threat analysis, including prompt injection through code and comments: Security.

CLI reference

One binary, strandline. Every command below links to itself; the common conventions come first.

Conventions

JSON shapes of the summary commands:

Setup and diagnostics

strandline init [OPTIONS]

strandline init && git add .gitattributes .strandline

strandline doctor [OPTIONS]

strandline doctor --fix

strandline install [OPTIONS] --agent <AGENTS>

strandline install --agent claude-code,cursor --dry-run

strandline status [OPTIONS]

strandline status --agent agent-a

strandline completions <SHELL>

strandline completions zsh > "${fpath[1]}/_strandline"

strandline mcp [OPTIONS]

strandline mcp --repo ~/src/your-repo

Index and merging

strandline index [OPTIONS]

strandline index --json | jq '.hotspots[:5]'

strandline hotspots [OPTIONS]

strandline hotspots --top 20

strandline merge-file [OPTIONS] <BASE> <OURS> <THEIRS>

strandline merge-file base.ts ours.ts theirs.ts --path src/api.ts -o merged.ts

strandline merge-driver [OPTIONS] <ANCESTOR> <CURRENT> <OTHER> [MARKER_SIZE] [PATH]

# what `strandline init` writes to .git/config
[merge "strandline"]
    name = Strandline structural merge
    driver = strandline merge-driver %O %A %B %L %P

strandline guard [OPTIONS] <BASE> <OURS> <THEIRS> <MERGED>

strandline guard base.py ours.py theirs.py merged.py --json

strandline merge-check [OPTIONS]

strandline merge-check --ours main --theirs agent-b --merged worktree

strandline lock regen [OPTIONS] [PATHS]...

strandline lock regen --pending --stage

strandline generated regen [OPTIONS] [PATHS]...

# .strandline/merge.toml
[[generated]]
path = "src/schema.gen.ts"
run  = "npm run codegen"

strandline weave install [OPTIONS]

strandline weave install

strandline weave status [OPTIONS]

strandline weave status --json

Coordination

All coordination commands accept --json (the shapes in Concepts), --repo <path> (any path inside the working tree, default .) and --agent <id> (default $STRANDLINE_AGENT_ID, else the current branch name). Those three are not repeated below.

strandline agent register [OPTIONS]

strandline agent register --task "Add invoice totals" --scope src/billing/

strandline agent list [OPTIONS]

strandline agent list --json | jq '.agents[].id'

strandline lease acquire [OPTIONS] <PATH>

strandline lease acquire src/routes.ts --ttl 45m --reason "wiring /invoices"

strandline lease release [OPTIONS] <PATH>

strandline lease release src/routes.ts

strandline lease renew [OPTIONS] <PATH>

strandline lease renew src/routes.ts --ttl 1h

strandline lease list [OPTIONS]

strandline lease list --all

strandline contract publish [OPTIONS]

strandline contract publish --json | jq '.published[] | {symbol, change}'

strandline contract changes [OPTIONS]

strandline contract changes --mark-seen

strandline collisions [OPTIONS]

strandline collisions --base main

strandline plan [OPTIONS] <TASKS>

strandline plan tasks.md --top-hotspots 15

Verify and repair

strandline verify [OPTIONS] <BRANCHES>...

strandline verify agent-a agent-b --base main --full

strandline repair [OPTIONS] --provider <PROVIDER> <BRANCHES>...

strandline repair agent-a agent-b --provider anthropic --max-attempts 2

strandline flaky [OPTIONS]

strandline flaky

strandline ci verify [OPTIONS]

# .github/workflows/verify.yml (step)
- run: strandline ci verify --with release/2026-11 --report-dir .strandline-ci
  env:
    STRANDLINE_API_KEY: ${{ secrets.STRANDLINE_API_KEY }}

Hosted mode

Local mode needs no account. Hosted mode is on when credentials are saved, or STRANDLINE_SERVICE_URL and STRANDLINE_API_KEY are set; STRANDLINE_LOCAL=1 forces local mode.

strandline login [OPTIONS]

strandline login --url https://strandline.example.com < key.txt

strandline logout [OPTIONS]

strandline logout

strandline whoami [OPTIONS]

strandline whoami --json

MCP tools

strandline-mcp is the MCP server your agents talk to. Every tool calls the strandline CLI, so it works the same in local and hosted mode.

It speaks MCP 2026-07-28 (stateless requests, server/discover, subscriptions/listen, the tasks extension for long-running tools, trace context in _meta) and 2025-era clients (initialize, resources/subscribe).

Running the server

Over stdio (strandline mcp, or the command strandline install --agent … writes into each agent's config) or Streamable HTTP:

strandline-mcp --http --port 8788     # endpoint /mcp, binds 127.0.0.1

On HTTP each request names its agent (X-Strandline-Agent) and working copy (X-Strandline-Worktree). Each tool runs strandline <cmd> --json --repo <repo> --agent <agent> and returns the JSON as structuredContent plus a short text summary. Each tools/call is a span continuing _meta.traceparent.

Server instructions sent to clients:

Tools

Resources and alerts

Both resources answer application/json: { "pending": [ContractChange, …] }.

A client opens subscriptions/listen with resourceSubscriptions: [<its pending URI>]. While it listens the server polls for contract changes every STRANDLINE_MCP_POLL_MS and, once per new relevant change, sends notifications/resources/updated for that URI; the client then reads the resource (symbols, signatures and why). A 2025-era client subscribes with resources/subscribe and gets notifications/resources/updated and a notifications/message (level warning) naming the changed symbols.

Self-hosting

Two supported installs, both tested end to end: a Helm chart for Kubernetes and a single-node Docker Compose install with TLS.

What runs

Images are multi-arch (amd64, arm64), signed with cosign (keyless, GitHub OIDC) and carry an SBOM.

Kubernetes (Helm)

kubectl create namespace strandline
kubectl -n strandline create secret generic strandline-secrets \
  --from-literal=DATABASE_URL='postgres://strandline_login:…@db:5432/strandline' \
  --from-literal=DATABASE_URL_MIGRATE='postgres://strandline_owner:…@db:5432/strandline' \
  --from-literal=STRANDLINE_RECEIPT_SIGNING_KEY="$(openssl rand -base64 48)" \
  --from-literal=STRANDLINE_ADMIN_TOKEN="$(openssl rand -hex 32)"
helm install strandline deploy/helm/strandline -n strandline \
  --set existingSecret=strandline-secrets \
  --set restate.ingressUrl=http://restate.restate:8080 --set restate.adminUrl=http://restate.restate:9070 \
  --set image.service.digest=sha256:… --set image.worker.digest=sha256:…

• Secrets only from existingSecret (keys listed in values.yaml); the migration Job alone gets the owner URL (DATABASE_URL_MIGRATE); service and workers get the non-owner login role that row-level security applies to.
• Migrations: a Job per release revision; new service pods stay not-ready (/readyz) until it has run, while the previous release keeps serving (migrations are expand/contract).
• Hardening: non-root (uid 1000), read-only root filesystem, all capabilities dropped, RuntimeDefault seccomp, no service-account token; startup, liveness and readiness probes; resources; PodDisruptionBudgets (service minAvailable: 1, worker maxUnavailable: 1); an HPA for the service (2–6 replicas at 70 % CPU); NetworkPolicies (default deny, then exactly the ports each component needs; narrow networkPolicy.workerEgressCIDRs to your Git host).
• Metrics: pods are annotated for Prometheus (prometheus.io/port 9464 / 9465); serviceMonitor.enabled=true with the Prometheus Operator. Alert rules and Grafana dashboards ship with the chart.
• Evaluation: --set postgresql.enabled=true --set postgresql.password=… --set restate.enabled=true --set secrets.create=true --set secrets.values.DATABASE_URL=… runs a single Postgres and a single Restate in the namespace. No backups, no HA.
• Sandbox: see Sandbox. The default is one pod per check under the gvisor RuntimeClass.

Single node (Docker Compose)

cd deploy/compose
cp .env.example .env            # STRANDLINE_DOMAIN, image tags
./init-secrets.sh               # random secrets in ./secrets (0600 dir, never in .env)
sudo install -d -o 1000 -g 1000 /var/lib/strandline/repos /var/lib/strandline/tmp   # STRANDLINE_DATA_DIR
echo "STRANDLINE_DOCKER_GID=$(stat -c %g /var/run/docker.sock)" >> .env
sandbox/build-images.sh v1      # the sandbox image; set STRANDLINE_SANDBOX_IMAGE
docker compose up -d --wait
docker compose exec service node packages/service/dist/main.js admin create-workspace --name my-team --plan team

Caddy terminates TLS: a public STRANDLINE_DOMAIN gets Let's Encrypt certificates automatically; localhost uses Caddy's internal CA. Everything else is on internal networks; secrets are Compose secrets read through *_FILE variables; every container has a healthcheck, restart: unless-stopped, a memory limit, and (except Postgres and Restate) a read-only root filesystem with all capabilities dropped. The service and worker log in to Postgres as strandline_svc, a non-owner role created on first start, so row-level security applies to them; only migrate uses the owner.

Upgrade: change the image tags in .env, then docker compose up -d (the migrate service runs first).

Sandbox

The worker runs your check commands (tests, builds, repairs), each in a sandbox: a container with no network, a read-only root, resource and time limits, as an unprivileged user, or a Firecracker microVM. In production the worker refuses to run without one.

• Docker Compose sets this up: the worker gets the host's Docker socket and starts sandbox containers next to itself. The daemon resolves their bind mounts on the host, so checkouts and scratch worktrees live in STRANDLINE_DATA_DIR, mounted at the same path in the worker.
• Kubernetes (the default): the worker never runs customer code itself. For each check it starts a pod next to itself under a RuntimeClass: gvisor (gVisor's runsc) by default, kata with worker.sandbox.isolation=kata, or your own class name with worker.sandbox.runtimeClassName (GKE Sandbox: gvisor). The check pod has its own service account with no token, none of the worker's secrets or environment, no network (a deny-all NetworkPolicy, no DNS) and only the run's worktree, mounted from the worker's volume by subPath; it runs as a non-root uid with a read-only root, no capabilities and CPU, memory and time limits. A ValidatingAdmissionPolicy (Kubernetes 1.30 or newer) refuses any other kind of pod from the worker's service account, whose Role covers only pods and their logs in the namespace.
• What you provide on Kubernetes: gVisor or Kata on the nodes that run workers, registered as a containerd (or CRI-O) runtime handler, and the RuntimeClass (worker.sandbox.runtimeClass.create=true lets the chart create it with handler runsc / kata); the toolchain image (sandbox/build-images.sh, pushed to your registry, worker.sandbox.image by digest); persistence for the worker (on by default); a CNI that enforces NetworkPolicies (without one the check pod still has no credentials, but could reach in-cluster services). Settings: worker.sandbox.kubernetes.* (per-check CPU, memory, tmpfs, start timeout, API server egress).
• Other backends: microvm on nodes with /dev/kvm (with sandbox/microvm/provision.sh output on the node in worker.sandbox.microvmDir, default /var/lib/strandline/microvm, mounted read-only and passed as STRANDLINE_MICROVM_DIR), or docker / podman where the worker pod reaches a runtime that sees worker.repoRoot at the same path (a dedicated sandbox node pool).

Backups and restore

• Physical + WAL (recommended): archive_mode and an archive_command to an archive volume (ship it to object storage; archive_timeout = 60 gives an RPO of a minute or less) and a nightly pg_basebackup -Ft -z -X stream. Restore = base backup + restore_command from the archive (point in time with recovery_target_time). A reference postgresql.conf ships with the installs.
• Managed Postgres: use the provider's PITR (it is the same mechanism); keep a logical pg_dump -Fc weekly as a second, provider-independent copy.
• Drill: make restore-drill does both restores into fresh Postgres containers and verifies row counts, every receipt's digest and HMAC signature, metering, and that the service runs on the restored database. Run it after changing backup settings and quarterly.
• Restate keeps workflow journals on its own volume; back it up with the same schedule, or accept that in-flight workflows restart from their last committed database state after a Restate loss (merge attempts are re-requested idempotently).

Sizing (measured)

Under load, two service replicas at 1 CPU / 512 MB and Postgres at 1.5 CPU / 1 GB carry 1,000 agents (about 15,000 requests/min plus about 5,000 webhook deliveries/min); Postgres CPU is the first limit. Start there and scale the database first, replicas second.