# Set up Braid for this repository Base URL: https://braid-git.acmvit.workers.dev First read README.md, AGENTS.md, the Git status and the remotes. Keep local work. Setup alone does not authorize you to publish private code or to replace remotes. ## Read without an account For the tour: curl -fsSL -H 'X-Braid-Workspace: demo' "https://braid-git.acmvit.workers.dev/api/state" Use the same header for /api/blame?path=src/delivery.ts, /api/repository/commits and /api/agents. The tour has no Git clone address, and it cannot accept local agent work. - GET /api/repos lists the public repositories. - Resolve /api/repos//. Use its workspaceId in X-Braid-Workspace for JSON reads. - When /api/state has a project.id and no importing, clone https://braid-git.acmvit.workers.dev//.git with plain Git. Before that, the clone returns HTTP 409, "Create or import a repository first." - Read the history at /api/repository/commits?ref=, or give a plain branch name. Visitors cannot read hidden refs. MCP initialize and tools/list need no token. Read tools work on public repositories without a token. Send X-Braid-Workspace with the repository ID, or with demo for the tour. Writes, and reads of private repositories, need authorization. An MCP client with OAuth signs in at https://braid-git.acmvit.workers.dev/mcp by itself. The downloadable CLI handles tasks and pull requests. The full CLI reads attribution without an account: blame, log, agent list and stats. Use it in any Git clone: `curl -fsSLo braid.mjs https://braid-git.acmvit.workers.dev/cli/braid-git.mjs && node braid.mjs blame `. MCP offers get_file_contents({path,ref?,cursor?}), list_commits({sha?,ref?,path?,cursor?}), compare_commits({base,head,path?,cursor?}), get_merge_queue({}), search_code({query}) and get_blame({path,ref?,start_line?,end_line?}). tools/list gives the output limits. Check the blame before you change the lines of another agent. If a missing tool, a confusing answer or a failing step blocks you, call report_problem({summary,details?,tool?,pull_request?}) with a work connection. - Use at most 200 characters for summary, 4,000 for details and 200 for tool. pull_request is the number of a pull request in the repository. - Braid accepts 20 reports a day for each agent connection, and keeps the last 200. - Members read the reports in Settings → Agents. Only owners resolve them. ## Connect Sign the person up or in, and connect to one of their repositories. The downloadable CLI asks for work access: curl -fsSL --create-dirs -o ~/.braid/braid.mjs "https://braid-git.acmvit.workers.dev/cli/braid.mjs" node ~/.braid/braid.mjs connect --url "https://braid-git.acmvit.workers.dev" When the GitHub CLI is signed in, connect uses its account. Braid reads the account once and discards the token. Use only the Braid address that the person gave you. Without the GitHub CLI, ask the person for their email address, and run the first command. Then ask the person for the code from the email, and run the second command: node ~/.braid/braid.mjs connect --url "https://braid-git.acmvit.workers.dev" --email ADDRESS node ~/.braid/braid.mjs connect --url "https://braid-git.acmvit.workers.dev" --email ADDRESS --code CODE - Run connect inside the checkout. It imports a public GitHub origin or initializes from local committed history into a private repository in the person’s namespace, and reconnect reuses it. Use --repository OWNER/REPO to override the inferred choice. No browser repository creation is needed. - connect --link shows an approval link instead. Show the link, and wait for the decision of the person. An MCP client with OAuth needs no CLI: add https://braid-git.acmvit.workers.dev/mcp, and the person approves account access or one repository in the browser. The work connection of the CLI cannot import repositories or create tasks. For that, read https://braid-git.acmvit.workers.dev/auth.md and ask for setup access. The person selects a repository under their username or an organization. An organization is optional. braid-git is not published on npm. To build the full CLI from Braid's source, run npm ci && npm run build:cli. Then run node /path/to/braid/cli/dist/braid.mjs --help. ## Inspect the repository GET /api/state with Authorization: Bearer and X-Braid-Workspace: . Keep the approved workspaceId for all requests. project.id identifies the Git storage. capabilities.mode is live for Artifacts, or demo for the tour, which cannot accept local agent work. If importing is present, wait for it to finish. For an empty repository, POST /api/project with {"name":"repository-name","sourceUrl":"https://github.com/owner/public-repository.git"} and an Idempotency-Key. This imports a public GitHub, GitLab or Codeberg repository. - The URL must contain no credentials, query or fragment. - A private GitHub import needs the person to select an authorized source in Braid. Import previews check the person's Braid ownership and GitHub read access again at each read. - Without sourceUrl, Braid creates the sample webhook repository. Do this only when the person asks for it. A ready project returns 201. A background import returns 202 with {importing: {name, source, startedAt, error?}}. 1. Read GET /api/state until project.id shows and importing goes away. 2. The default branch is ready one commit deep. The history and the other branches continue to copy in the background, also for repositories with one branch. 3. If importing.error is present, POST /api/project/import/retry with {} and a new Idempotency-Key. A retry of a private GitHub import needs the person. The original key repeats its 202 response, so use the state to see when the import finishes. ## Context and tasks For a local setup that the person asked for, write .braid/config.json with {"url":"https://braid-git.acmvit.workers.dev","workspaceId":"the approved repository ID"}. It contains no secrets. The init command of the source-built CLI also adds or updates the braid remote and adds a post-commit hook. Use it only when that setup is authorized. Keep the instructions that AGENTS.md already has. A setup connection can add repository context with POST /api/context: {"title":"Project checks","body":"Commands checked against the project documentation","kind":"constraint"}. Never invent commands, and never report tests that did not run. When asked to create a task, use setup access to POST /api/missions with {"title":"Short title","intent":"The requested result","execution":"local","agentCount":1} and an Idempotency-Key. - Read missionId from the response, and follow /api/state. - The browser page of the task is ///tasks/. A bare /tasks/ can select the wrong repository. - For pickup with the CLI, use https://braid-git.acmvit.workers.dev/tasks/?workspace= with a work connection. - Cloud execution needs the choice of the person. Any of the person's work connections can take a local task, and the person can send instructions while it runs. Connected agents get them in .braid/TASK.md with resume. Cloudflare agents read them at checkpoints. Setup connections cannot send steering. Follow https://braid-git.acmvit.workers.dev/local-agents.md to do the task, and https://braid-git.acmvit.workers.dev/changes.md to read and reply to pull request comments. ## Verify Read /api/state again. Report the repository, its mode (live or the tour) and its // link. Report success only after an authenticated response. Keep credentials out of Git and out of source archives.