Protocol 1.0

The system of record for software evolution

Converge is a transactional software-state store for coding agents. Git is the object store. The product is the transition from one immutable snapshot to the next.

It is not GitHub without a UI. There are no pull requests, comments, stars, or dashboards. Agents resolve a snapshot, work in an isolated workspace, submit a change, attach evidence, and integrate with compare-and-swap.

Hosts

Marketing and documentation live on the product host. Agents, CI, and the CLI talk to the agent host.

HTTP control plane:

https://converge.seeyon.chat/v1

Git data plane:

git@converge.seeyon.chat:payment-service.git

Point the CLI at the agent host:

export CONVERGE_SERVER=https://converge.seeyon.chat

Quickstart

Canonical path for a coding agent. Git stays Git. Converge owns remote software-state that Git does not understand.

1. Resolve master into a snapshot Pin work to an immutable commit, never a moving branch name.
2. Create a workspace One agent, one task, one frozen base.
3. Clone, edit, commit with Git Converge does not wrap clone, add, commit, or rebase.
4. Push the workspace ref and submit a Change Base + result + intent + principal.
5. CI publishes Evidence against the exact commit Then integrate with compare-and-swap.

export CONVERGE_SERVER=https://converge.seeyon.chat

converge snapshot resolve payment-service master --json
converge workspace create payment-service --base snp_123 --task TASK-8291

git clone git@converge.seeyon.chat:payment-service.git
cd payment-service
git checkout abc123
# edit locally
git commit -m "Fix invoice total rounding"
git push origin HEAD:refs/workspaces/wrk_01928

converge change submit payment-service \
  --workspace wrk_01928 \
  --commit def456 \
  --intent "Fix invoice rounding"

converge integrate payment-service chg_8291 \
  --target master \
  --expected abc123

Install

The converge binary is both CLI and server.

curl -fsSL https://www.converge.seeyon.chat/install.sh | sh
export CONVERGE_SERVER=https://converge.seeyon.chat
converge auth login

Windows PowerShell:

irm https://www.converge.seeyon.chat/install.ps1 | iex
$env:CONVERGE_SERVER = "https://converge.seeyon.chat"
converge auth login

Direct downloads: Windows x64, macOS Apple Silicon, macOS Intel, Linux x64, and Linux arm64. Every artifact is covered by SHA256SUMS.

Serve a node:

converge serve

Agents should pass --json on every command. Do not parse prose to decide success.

After the first successful login, the CLI remembers the selected server. Explicit --server and CONVERGE_SERVER values take precedence over the saved server.

Repository

A repository is a namespace and a bare Git object store. It is not a project-management container. New repositories default to refs/heads/master.

POST /v1/repos
{
  "name": "payment-service"
}

{
  "id": "payment-service",
  "default_ref": "refs/heads/master"
}

Identifiers must match ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$. DELETE archives by default.

Snapshot

A snapshot is an immutable software state. In V1 the code component is a Git commit SHA. Agents should work from a snapshot ID or commit, not from the mutable name master.

POST /v1/repos/payment-service/snapshots/resolve
{ "ref": "refs/heads/master" }

{
  "snapshot": "snp_01J...",
  "commit": "83ab291..."
}

Ephemeral agents can fetch an archive of exactly that commit:

GET /v1/repos/{repo}/snapshots/{commit}/archive

Workspace

A workspace is one agent task on one base snapshot. It is logical metadata. Converge does not keep a server-side checkout. The filesystem belongs to the agent runtime.

POST /v1/repos/payment-service/workspaces
{
  "base": "snp_01J...",
  "task_id": "TASK-8291",
  "working_set": ["src/payment/**"]
}

{
  "id": "wrk_01928",
  "ref": "refs/workspaces/wrk_01928",
  "potential_conflicts": []
}

Working sets are advisory. They never create file locks. Overlap with other active workspaces is reported; V1 does not serialize conflicting work. Statuses: active, submitted, abandoned, expired.

Change

A change is the unit of proposed evolution: base state + result state + intent + producer + evidence. It replaces a machine-oriented pull request.

POST /v1/repos/payment-service/changes
{
  "workspace": "wrk_01928",
  "result_commit": "def456",
  "intent": "Fix invoice rounding"
}

Statuses: created, validating, ready, integrated, rejected, superseded, conflicted. Every submitted change keeps refs/changes/{id}/head.

A change becomes ready when required evidence exists in the required state. Readiness does not integrate. Integration is a separate explicit action.

Evidence

Evidence is machine-generated proof about a change. It is more general than a CI status. Converge stores state, summary, producer, and an external URL — not logs, coverage files, or binaries.

POST /v1/repos/payment-service/changes/chg_8291/evidence
{
  "type": "test",
  "name": "unit-tests",
  "state": "passed",
  "producer": "ci:jenkins-prod",
  "summary": "341 tests passed",
  "details_url": "https://ci.internal/jobs/98182"
}

Built-in types: test, build, lint, typecheck, security, policy, review, benchmark, compatibility, custom. States: pending, passed, failed, warning, cancelled.

A coding agent must not be allowed to forge CI evidence. Evidence write is capability-controlled.

Principal and delegation

Every actor is a principal. There is no User object and no Guest / Developer / Maintainer roles.

agent:codex:session-38192
ci:jenkins-prod
validator:security
integrator:master
system:provisioner

Requests should carry principal, delegated_by, task_id, and credential_id. Authorization is capability-based and repository-scoped, for example repo:payment-service:change.create. Ordinary coding agents must not receive ref:refs/heads/master:update.

Integration

Integration is the controlled transition of an accepted change into an authoritative ref. Coding agents should not push to master.

POST /v1/repos/payment-service/integrations
{
  "change": "chg_8291",
  "target_ref": "refs/heads/master",
  "expected": "abc123"
}

{
  "integration": "int_19382",
  "previous": "abc123",
  "current": "def456",
  "snapshot": "snp_01JAC..."
}

The ref update is atomic compare-and-swap, equivalent to git update-ref refs/heads/master def456 abc123. If master has moved, Converge returns 409 with REF_CONFLICT.

{
  "error": "REF_CONFLICT",
  "expected": "abc123",
  "actual": "xyz999"
}

Converge never rewrites source to resolve merge conflicts. The agent rebases or regenerates, re-validates, and retries.

Agent workflow

The product model is a pipeline, not a repository page:

Snapshot → Workspace → Change → Evidence → Policy → Integration → new Snapshot

CI must build the exact result commit, not master. That remains reproducible if master moves while the job sits in a queue.

Concurrency

A stale base is a normal concurrent condition. Two agents may start from snapshot A. The first CAS to B succeeds. The second CAS A → C fails with REF_CONFLICT. Agent 2 resolves snapshot B, replays, validates, and CAS B → D.

V1 does not automatically serialize overlapping working sets. Agents may continue, wait, narrow the set, or coordinate outside Converge.

HTTP API

Control plane is HTTP + JSON at https://converge.seeyon.chat/v1. Timestamps are UTC ISO 8601. Mutations return stable identifiers. Mutation APIs should accept Idempotency-Key.

Repositories

POST /v1/repos

GET /v1/repos

GET /v1/repos/{repo}

DELETE /v1/repos/{repo}

Snapshots

POST /v1/repos/{repo}/snapshots/resolve

GET /v1/repos/{repo}/snapshots/{snapshot}

GET /v1/repos/{repo}/snapshots/{commit}/archive

Workspaces

POST /v1/repos/{repo}/workspaces

GET /v1/repos/{repo}/workspaces/{workspace}

DELETE /v1/repos/{repo}/workspaces/{workspace}

Changes

POST /v1/repos/{repo}/changes

GET /v1/repos/{repo}/changes/{change}

GET /v1/repos/{repo}/changes

Evidence

POST /v1/repos/{repo}/changes/{change}/evidence

GET /v1/repos/{repo}/changes/{change}/evidence

PUT /v1/repos/{repo}/changes/{change}/evidence/{evidence}

Integration and refs

POST /v1/repos/{repo}/integrations

GET /v1/repos/{repo}/refs/{ref}

PUT /v1/repos/{repo}/refs/{ref}

Blind updates to authoritative refs are denied. The current value must be supplied for CAS.

Hooks and audit

POST /v1/hooks

GET /v1/hooks

DELETE /v1/hooks/{hook}

GET /v1/audit

Observability: /healthz, /readyz, /metrics.

CLI

First-class V1 interface. The same binary serves the node. It does not wrap ordinary Git.

converge repo create payment-service
converge snapshot resolve payment-service master --json
converge workspace create payment-service --base snp_123 --task TASK-8291
converge change submit payment-service --workspace wrk_01928 --commit def456 --intent "Fix invoice rounding"
converge evidence add payment-service chg_8291 --type test --name unit-tests --state passed
converge integrate payment-service chg_8291 --target master --expected abc123
converge audit --repo payment-service --task TASK-8291

Git

Git remains the storage substrate. Transport is SSH. Converge delegates to system Git: git-upload-pack, git-receive-pack, git-update-ref. It does not implement packfiles or the Git wire protocol.

Agents may write refs/workspaces/*. Converge manages refs/changes/*. Protected by default: refs/heads/master, refs/tags/*.

SSH allows only Git pack operations. No shell, scp, sftp, or forwarding. OpenSSH plus AuthorizedKeysCommand or certificates maps the principal onto Converge capabilities.

Authentication

HTTP uses bearer JWT. Required claims: sub, exp. Recommended: task_id, delegated_by, scope, jti.

{
  "sub": "agent:codex:session-38192",
  "task_id": "TASK-8291",
  "delegated_by": "human:zhang",
  "scope": [
    "repo:payment-service:read",
    "repo:payment-service:workspace.create",
    "repo:payment-service:change.create"
  ]
}

Long-lived personal access tokens are discouraged. Future versions may add mTLS and SPIFFE. The architecture does not assume a principal owns a permanent credential.

Events

After-transition work is asynchronous. V1 delivery is webhooks, at-least-once, HMAC-signed. Every event has a unique event_id. Failed delivery must not roll back an already completed transition.

POST /v1/hooks
{
  "url": "https://ci.internal/converge",
  "events": ["change.created", "change.ready", "ref.updated"]
}

Core events include workspace.*, change.*, evidence.*, snapshot.created, integration.succeeded, integration.failed, ref.updated.

Policy

V1 supports simple declarative required-evidence policy. There is no general-purpose policy language.

{
  "target": "refs/heads/master",
  "required_evidence": [
    { "type": "test", "name": "unit-tests", "state": "passed" },
    { "type": "build", "name": "build", "state": "passed" }
  ]
}

Unsatisfied requirements fail integration with POLICY_DENIED. Blocking hooks have a 5 second default timeout. Slow checks should publish evidence instead.

Deployment

V1 is one binary, one host, system Git, SQLite in WAL, OpenSSH, a persistent volume. Language is Go. Kubernetes is unnecessary.

/opt/converge/converge
/data/converge.db
/data/repos/

Design envelope: 10,000 repositories, 1,000 active agents, 100,000 changes/day. Metadata p95 < 100ms. Ref transition p95 < 250ms, excluding external blocking hooks.