# Elffuss Braid

> Version control for repositories where many AI agents land changes at the same time. Written from scratch in Rust, with git at the edges. Version 0.1, Apache-2.0.

Each agent commits in a workspace of its own over one shared store, and landing on the main branch is one short step that agents take in turn: a fast-forward, or a rebase that merges only the files both sides touched. Conflicts come back as data, with exit status 2, and every command has a JSON form. Braid imports a git repository's whole history bit for bit, and `braid git sync` keeps a git remote such as GitHub in step. This is version 0.1: keep git as the source of truth.

To set braid up in a project, a coding agent follows agents.md. Setting it up adds to the project's AGENTS.md a section between `<!-- braid:start -->` and `<!-- braid:end -->` with the rules every agent session follows, and the line `@AGENTS.md` to CLAUDE.md and GEMINI.md where they exist; nothing of braid's own goes into git. The prompt to give it: Install braid in this project and set it up for agents, following https://braid.elffuss.com/agents.md (read it whole, with curl -fsSL)

To work from several machines, a repository can live on BraidHub (https://braidhub.elffuss.com), a braid server where people and agents sign in with GitHub and agents on any machine land on the same main branch, one after another. In a linked repository, `braid land` uploads what the hub lacks and lands there, with the output and exit statuses of a local landing. A repository is private unless its owner makes it public, and can keep a GitHub repository as its mirror, to which every landing on the default branch is pushed as a fast-forward. Coding agents that work with BraidHub follow its own guide, https://braidhub.elffuss.com/agents.md. BraidHub is new in version 0.1: for anything that matters, keep a GitHub mirror as the source of truth.

## Docs

- [Install braid and set it up for agents](https://braid.elffuss.com/agents.md): for coding agents, to read whole. Installing with cargo, setting up a git project with `braid agents init`, each session's workspace (where git does not run), conflicts, keeping the git remote in step, or making one where there is none, undoing, and what not to do.
- [BraidHub for coding agents](https://braidhub.elffuss.com/agents.md): for coding agents that work with BraidHub, to read whole. Signing in once per machine with `braid login`, the one question to ask the user (whether to publish the new projects they start, kept by `braid hub autopublish on|off`), publishing a project, cloning one, and landing through the hub.
- [README](https://raw.githubusercontent.com/KikoCis/elffuss-braid/main/README.md): what braid is, the quick start, working with git, BraidHub, status and roadmap, and ratios against git.
- [Design](https://raw.githubusercontent.com/KikoCis/elffuss-braid/main/docs/design.md): the store, landing, history, workspaces, the git bridge and sync, and how it is tested.
- [Format v1](https://raw.githubusercontent.com/KikoCis/elffuss-braid/main/docs/spec/format-v1.md): the exact bytes of ids, trees and changesets, with golden vectors.
- [BraidHub protocol](https://raw.githubusercontent.com/KikoCis/elffuss-braid/main/docs/hub.md): what BraidHub and braid say to each other over HTTP: sign-in, tokens, repositories, permissions, objects, landing, mirrors and limits.

## Optional

- [AGENTS.md](https://raw.githubusercontent.com/KikoCis/elffuss-braid/main/AGENTS.md): the same guide, and how to work on braid itself.
- [Contributing](https://raw.githubusercontent.com/KikoCis/elffuss-braid/main/CONTRIBUTING.md): building, testing, and the rules for changes.
- [Source](https://github.com/KikoCis/elffuss-braid): the repository on GitHub.
- [BraidHub](https://braidhub.elffuss.com/): the hub's website: signing in with GitHub, your repositories, tokens for CI, and the access to your GitHub repositories that mirrors need.
- [Site](https://braid.elffuss.com/): the same in English and Spanish, with three agents landing on one main.