# BraidHub for coding agents Instructions for a coding agent that works with BraidHub. Read this file whole before you run anything, as it is written: fetch it with `curl -fsSL https://braidhub.elffuss.com/agents.md` rather than with a tool that summarises pages, and run its commands exactly as they are given. BraidHub is a braid server. Repositories live on it; people and agents sign in with GitHub; agents on any machine land on the same main branch, one after another, with no fetch, rebase and push loop. A repository can keep a GitHub repository as its mirror: after each landing on its default branch, the hub pushes it there as a fast-forward, so the people who work with git keep doing so. More at , and the protocol in [docs/hub.md](https://github.com/KikoCis/elffuss-braid/blob/main/docs/hub.md). Repositories are private unless their owner makes them public. For anything that matters, keep a GitHub mirror: it holds every change that lands, as plain git. ## What you need - braid 0.1.0 or newer: `braid --version`. To install or update it, follow "Install" in . - The network, to `https://braidhub.elffuss.com`. A sandboxed harness may block it: ask the user to allow it. ## Sign in, once per machine ```bash braid hub whoami || braid login ``` `braid hub whoami` says who is signed in, and fails when nobody is. Then `braid login` prints a web address and a code on standard error. **Show both to the user, word for word, and ask them to open the address in a browser where they are signed in to GitHub, enter the code and approve.** braid waits until they do, then saves a token that only this user can read. The token reads, writes and lands on the repositories the user's GitHub account can, for 90 days; after that, `braid login` again. Never print, copy or commit the token, and never put it in a command line, a URL or a file of the project. A CI job or a container gets its own token, made on the hub's website under "Tokens" with only the rights it needs, and passed in the `BRAID_TOKEN` environment variable from the CI's secrets. ## The one question to ask: publish new projects to BraidHub? The first time you start a new project for this user, check whether they have answered already: ```bash braid hub autopublish ``` - `on`: publish every new project you start (below), privately. - `off`: never publish on your own; publish only when the user asks. - `unset`: ask the user, once, in these words or close to them: *"Should I publish the new projects I start to BraidHub, privately, so that agents on your other machines can work on them too? You can change this at any time."* Then record the answer, which braid keeps for every project: ```bash braid hub autopublish on # or: braid hub autopublish off ``` Never ask again while the answer is recorded. Never publish a project the user did not start with you (one they cloned from elsewhere, for instance) without asking first, whatever the answer. ## A new project When you create a new project with the user, set it up with braid from the start (as in "Set up a project" of ). Once it has a first changeset on its main branch, and autopublish is `on`: ```bash braid hub publish ``` It creates a private repository on the hub, uploads every branch, and links this repository to it: from then on `braid land` lands on the hub. The repository is named after the project's directory, made valid (characters outside `A-Z a-z 0-9 . _ -` become `-`, and a run of `-` one; a leading `.` or `-`, a trailing `-` and a trailing `.git` go), or after the name given as its argument. It prints the repository's address (`Published / at https://braidhub.elffuss.com//`): give the user that address. Add `--public` only when the user asks for a public repository. If the user wants the GitHub copy, create the GitHub repository first (empty) and add `--mirror https://github.com//.git`; the user grants the hub access to their repositories once, on the hub's website. ## A project that is on the hub already On a machine that does not have it yet: ```bash braid hub clone / cd /.braid/work/main ``` It makes a local repository in ``, linked to the hub, with a first workspace on the hub's default branch, and prints the workspace's directory: `/.braid/work/`, here for a default branch called `main`. Work there, or in a workspace of your own (`braid workspace add`). In a large repository, `braid hub clone / --paths ...` (the directory before `--paths`) brings only the trees under those prefixes. Such a sparse clone has no workspace, since a workspace is a whole checkout: it changes files with `braid change create ... --land main` only. ## Every session Nothing changes from braid's own rules (the braid section of the project's `AGENTS.md`): work in a workspace of your own, commit, and land. - `braid land` in a linked repository fetches from the hub, uploads what the hub lacks of your changesets, lands them there, and moves your workspace onto the new head. Its output and exit statuses are those of a local landing: exit 2 means conflicts, listed as data. `braid update` brings them into your working copy: edit the conflict markers out of each file with a content conflict, settle every other conflict and mark it with `braid resolve `, then `braid commit` and land again. - `braid update` fetches first, so you build on what the other agents landed. - `braid hub status` shows the link and how each branch compares with the hub. - Without the network, `braid land --local` and `braid update --local` (or `BRAID_HUB=off` in the environment) work on the local repository only; the next `braid land` takes the changesets landed locally to the hub first. ## Security - The hub never runs code from a repository: no hooks, no builds, no CI. - A private repository is visible only to its owner, its collaborators and, with a GitHub mirror, the people who can push to that GitHub repository. - `braid logout` revokes this machine's token on the hub and deletes it here.