knotless

Git that lives in your atproto account.

It works on any stock PDS, with nothing to install. People push with plain git through a remote helper, and agents do the same over MCP.

A knotless repository is a handful of records in your own atproto repo. There is no git server and no knot. The repository moves with your account and is in your CAR backups, and anyone can clone it from your PDS directly.

Forks, pulls, issues and reviews are records too, each in its author's account. One optional server, knotless-serve, adds a read cache, an index of pulls and issues, a gateway for collaborators, and web pages. It is cheap to run.

curl -fsSL https://knotless.dev/install.sh | sh   # knotless, git-remote-knotless, knotless-mcp, and the runner, labeller and reviewer
knotless login alice.bsky.social                   # OAuth, in your browser

git push knotless://alice.bsky.social/my-project main
git clone knotless://alice.bsky.social/my-project

knotless.dev runs knotless-serve, and hosts knotless's own repository: chadtmiller.com/knotless.

What it does

git push, fetch and clone over knotless:// URLs. knotless-serve also serves reads over git smart HTTP, partial and shallow clones included.
Commits, branches, reviews and merges from the CLI or MCP, with no clone.
Forks, pulls, reviews, issues, protected branches and a merge queue. Collaborators push through a gateway the owner chooses.
Private repositories in permissioned spaces, where the pulls, issues and comments are as private as the code.
An MCP server for agents: over stdio on your machine, or over HTTP from knotless-serve.
CI: knotless-run runs workflows in containers on pushes and pulls, and writes checks that gate merges.
Read-only web pages for code, history, diffs, pulls, issues and checks, with syntax highlighting and Mermaid diagrams, on a phone or a desktop.
atproto's moderation: hides, blocks, reports, and takedowns published as labels.

How it works

flowchart LR
  you[git, knotless CLI,<br/>or an agent over MCP] -->|XRPC| pds[(Your PDS:<br/>dev.knotless.* records<br/>and pack blobs)]
  others[Collaborators] -->|service token| gw[Gateway]
  gw -->|writes as you| pds
  pds --> feed[Jetstream]
  feed --> serve[knotless-serve:<br/>cache, index, web pages]
  feed --> run[knotless-run:<br/>workflows]
  run -->|checks| ci[(Runner's PDS)]
  readers[Anyone] -->|clone, browse| serve
  readers -->|clone| pds

Four record types in the owner's account hold a repository:

Record	Key	Holds
`dev.knotless.repo`	name	the repository's `key` (a TID), description, default branch, collaborators, gateway and branch rules
`dev.knotless.ref`	`<key>.<hash of ref name>`	one ref's target, and a generation counter
`dev.knotless.claim`	`<key>.<hash>.<generation>`	the lock on one generation of a ref
`dev.knotless.pack`	`<key>.<tid>`	an immutable, self-contained git pack, inline when small and in blobs when not

A push creates the claim for the ref generation it read, in the same applyWrites as the ref update. The PDS accepts only the first create of a key, so each ref has its own compare-and-swap, and agents pushing to separate branches never contend.

The keys share the repository's prefix, so one listRecords reads a repository's refs, or its newest packs. Once a repository holds more than 32 packs, they are folded into one, so a clone stays a few reads however long the history is.

The design pages cover the rest: the limits of a stock PDS, the failure cases, the trust model and the prior art.

Performance

A warm push is two round trips to the PDS, and a fetch of a small push is one. Against the reference PDS on the same machine, with 50 ms of round-trip time added:

	p50
`git push`, one small commit	223 ms
`git fetch`, one new commit	177 ms
`knotless repo commit`, no checkout	366 ms
`git clone`, compacted	158 ms
16 agents pushing 16 branches at once	443 ms total

Performance has every measurement and how it was taken.

Documentation

Getting started: install, log in, push, commit without a checkout.
Collaborating: sharing, forks, pulls, reviews, merging, moderation.
Private repositories.
Agents: connect Claude Code, Claude Desktop, Cursor or claude.ai.
Running knotless-serve: the cache, appview, gateway and web pages.
Workflows: CI with knotless-run.
Command reference: every command, flag and environment variable.

The docs index lists every page.

Components

knotless: the CLI and git-remote-knotless. They talk to PDSes directly.
knotless-mcp: the MCP server.
knotless-serve: the optional read cache, appview, gateway, moderation service and web pages, in one binary that fits a small VPS.
knotless-run: the workflow runner.
knotless-triage: the triage bot, which labels issues with a classifier's choices.
web: the SvelteKit pages that knotless-serve hands requests to.

Development

just setup    # npm install in harness/ and web/, llvm-tools for coverage
just test     # every test, against the npm reference PDS
just fmt      # rustfmt and oxfmt
just lint     # rustfmt, oxfmt, clippy and svelte-check

Tests cover every line and function, and CI fails below that. Development covers the test harness, screenshots and agent scenarios. AGENTS.md says how changes are made and landed.

Status

knotless runs knotless.dev, which hosts knotless's own development. Not done yet: verifying refs against signed repository commits (Known gaps).

License

MIT or Apache-2.0, at your option: LICENSE-MIT, LICENSE-APACHE.

johnandersen777.bsky.social/knotless Switch repository Loading…