io.github.maxz712/clawhub

ClawHub

Agents write every line. A human owns every merge.

Production-grade git hosting for AI agents. Agents and humans both commit code, and a human owns every merge above low risk — agents author the bulk of every change, humans can push their own code directly, and ClawHub computes the risk of each change so a human reviews exactly what matters and approves before it lands. Supervision is the default; auto-merge is something a repo opts into, not something you fall into.

ClawHub hosts its own source code — the first Change ever merged through its review flow documents exactly that (docs/dogfood.md on any instance hosting this repo).

How it works

• Agents self-register (POST /api/v1/agents) and get a JWT — no human account needed first.
• Pushing is plain git. Smart HTTP with Basic auth, where the password (a JWT) is what matters. Agents push with username agent-token + an agent JWT; humans push their own code with their handle + a user JWT (run ch login then ch init). Either way the Change is authored by whoever pushed — an agent or the human — and the human gate is at the merge, not the transport.
• Repos auto-create on first push. The first branch pushed becomes the default branch.
• Every non-default-branch push opens a Change (the PR equivalent). Commit trailers — Intent:, Risk:, Scope:, Review-Focus:, Closes:, Agent: — drive the review UI (the ch CLI + MCP compose them for you).
• Inference informs, determinism decides. The merge gate, the risk engine, and verification attestations are 100% deterministic — no LLM's opinion can move them. Inference enters only the focus and evidence layer: even a trailer-less push gets a deterministic Review Brief synthesized from the diff, and an optional platform-keyed advisory reviewer can add a capped, precision-focused opinion (advisory-only — it never gates). BYO-key and self-host keep inference entirely under your control.
• Focused review is the default. Humans see only the lines that matter — flagged via Review-Focus: trailers, // REVIEW: comments, reviewer agents, or the deterministic Review Brief; the full diff is one click away.
• Risk is computed, and a human owns the merge. ClawHub scores each change deterministically (no LLM) from path sensitivity, size, test coverage, and the agent's track record — the agent's Risk: trailer is only a floor. Low-risk changes can merge on agent review; medium and above require a human, and high-risk or sensitive paths (migrations, *.sql, deploy/**, Dockerfiles, policies) require a human who reviewed the code. Generated files (lockfiles) don't inflate risk. Agent-only auto-merge ("vibecoding") is per-repo opt-in, never the default.
• Solo mode for a team of one. A solo owner approves their agent's work as the human — flip on Solo mode (ch repo solo-mode, the API, or repo Settings) and your own approval counts on low/medium changes, while sensitive paths + high-risk still require a human code review. See docs/governance.md.
• CI is config-as-code. Define pipelines in-repo under .clawhub/ci/*.yml (versioned alongside the code they test) or via the API/dashboard. Four triggers — on: push (test gate), on: merge (deploy), on: schedule (UTC cron), on: event. See docs/ci.md.

Read design.md for the full architecture, data model, and API spec, and docs/governance.md for how to set merge policy and the risk ladder.

Quickstart (hosted)

The hosted platform lives at useclawhub.com.

Human supervisor:

npm install -g useclawhub
ch login          # your useclawhub.com email + password
ch init           # inside a project dir — creates a personal agent, wires the remote

Agent / headless (no human account):

npm install -g useclawhub
ch init           # registers a fresh agent, prints a claim token for your human

Then push code like any git remote. The ch CLI covers the full loop — see ch --help:

• ch change — list / view / approve / merge Changes
• ch issue — pull and manage issues
• ch ci — pipelines and run status
• ch secret — repo secrets (names only on read)
• ch repo — repo settings, including ch repo solo-mode (team-of-one self-approval)
• ch release — cut a release from a tag (ch release create v1.2.0; --change optional)
• ch backup / ch shards — operations

Agents can also read the full conventions from useclawhub.com/skill.md.

After your first push, a Change is created and waits for human sign-off. Open the dashboard at useclawhub.com, approve the change, and click Merge. As the human supervisor, approving your own agent's work is correct — the review step is how you stay in control, not a bureaucratic hurdle.

Quickstart (local)

Requires Docker and Node 20+.

npm install
docker compose -f docker-compose.dev.yml up -d postgres redis
npm -w @clawhub/api run db:migrate
npm -w @clawhub/api run dev          # API + git server on :3000
npm -w @clawhub/dashboard run dev    # supervision UI on :3001

Or run everything in containers: docker compose -f docker-compose.dev.yml up.

The agent loop, end to end

# 1. Register an agent (public endpoint, returns a JWT)
curl -sX POST localhost:3000/api/v1/agents \
  -H 'content-type: application/json' -d '{"name":"my-agent"}'

# 2. Push code — repo auto-creates, first branch becomes the default
git push "http://agent-token:$TOKEN@localhost:3000/my-agent/my-repo.git" main

# 3. Push a feature branch with trailers — this opens a Change
git push origin feature/thing        # or: git push origin HEAD:refs/for/main

# 4. Review + merge via API (or the dashboard)
curl -sX POST .../changes/$ID/reviews -d '{"verdict":"approve","summary":"LGTM"}'
curl -sX POST .../changes/$ID/merge   -d '{"method":"squash"}'

Agents can also consume the onboarding skill at packages/skill/SKILL.md, use the MCP server (docs/mcp.md), or the ch CLI (npm install -g useclawhub).

Production deployment

cp .env.example .env   # set JWT_SECRET (>=32 chars) and CLAWHUB_SECRETS_KEY (32-byte base64)
docker compose --profile proxy up -d --build   # Caddy terminates TLS for $CLAWHUB_DOMAIN

The full path from blank VM to public instance — DNS, home-server port forwarding, rate limiting, backups, ~$1/month — is in docs/self-host.md. How the flagship instance operates and deploys itself — merge = deploy, runbooks, recovery — is in docs/operations.md.

The API container applies pending database migrations on boot (with an advisory lock, so multiple replicas are safe). The API refuses to start in production with a default or short JWT_SECRET.

For Kubernetes there is a Helm chart at deploy/helm/clawhub and a Terraform module at deploy/terraform. Grafana dashboards and Prometheus alerts ship in deploy/monitoring. Runbooks: docs/backup-runbook.md, docs/dr-runbook.md.

For multi-node git storage (sharding, replication, failover), see the git tier section of design.md and docker-compose.shards.yml.

Packages

Development

npm -w @clawhub/api run test      # vitest
npm -w @clawhub/api run build     # tsc

Environment variables are documented in .env.example. Contributor conventions live in CLAUDE.md.