Braid

Combining the interactive coding agent experience with a graph-based workflow.

Braid turns a ticket into a pull request by running an interactive coding agent through a graph of steps, each step checked deterministically instead of trusting the agent's word. The graph follows OpenSpec and feature branching, the practices teams already trust. Essentially vibe coding meets traditional software engineering, with a human in the loop at the critical steps.

🚧 Beta - still under heavy development 🚧

How it works

flowchart LR
    agent["Interactive<br/>coding agent"]:::agent
    dag["Graph workflow<br/>(DAG)"]:::script
    se["OpenSpec +<br/>feature branching"]:::human
    braid(["Braid"]):::forge
    ui["One UI to watch<br/>and steer both"]:::agent
    agent --> braid
    dag --> braid
    se --> dag
    braid --> ui

    classDef agent  fill:#1e3a5f,stroke:#60a5fa,color:#e0f2fe
    classDef human  fill:#78350f,stroke:#fbbf24,color:#fef3c7
    classDef script fill:#1f2937,stroke:#9ca3af,color:#f3f4f6
    classDef forge  fill:#14532d,stroke:#4ade80,color:#dcfce7

	Combines the interactive coding agent experience with a graph-based workflow.
	OpenSpec and feature branching, the practices teams already trust.
	One rich UI for both the workflow and the agent.
	Trustworthy on mid-sized models, with deterministic checks on every step
	Build the right graph for the job: eleven pipelines built in, or your own as YAML in the repository
	A methodology proven over a long software career, for AI agents.

How the graph system works

Braid treats work as a graph, not a single prompt.

• Agent steps do the creative work.
• Scripted checks verify repository state.
• Human gates approve the important moves.
• State transitions decide what can run next.

Issue → Explore → Propose → Review → Apply → Test → Pull request → Merge & archive
↑ revise loop  ·  ↑ fix loop

The point: the repo, not the agent, decides when work is ready.

The pipelines

A pipeline is a graph, written as YAML. A run names the one it uses, in the New Run wizard or with pipeline on POST /api/runs. Eleven are built in:

Pipeline	What it does
thorough	The default. Explore, propose, review, apply, code review, the tests and a judge, pull request, archive
minimalist	Propose, apply, the tests and a judge, pull request, archive
quick-fix	A fix and its tests straight from the brief, with no OpenSpec change
docs	Documentation and comments, then a link check; no tests and no OpenSpec change
plan	A new project's PLAN.md and its OpenSpec proposals, for your review; no code
git-flow, git-flow-minimalist, git-flow-quick-fix, git-flow-docs	The four above on feature/* branches, cut from and merged into develop
git-flow-release, git-flow-hotfix	A release from develop, or a hotfix from main, tagged and merged back

In thorough, each stage is checked before the next starts:

• the proposal must pass openspec validate --strict;
• four independent reviews read it, and it is revised at most twice;
• a person approves the proposal, the merge and the archive, or auto-approve answers those gates for them;
• Braid runs the tests itself, a judge opens a UI change in a real browser, and an agent fixes what failed, for at most two rounds;
• the merge waits for the pull request's own checks.

A repository can replace a pipeline or add its own in .osf/pipelines/<name>.yaml. The guide lists every step.

This is how we move from vibe coding toward reliable software systems: the agent stays creative, but the workflow keeps it constrained, reviewable, and checkable.

Run it locally

You need Python 3.12 with uv, Node 22+, git, lsof, and opencode 1.18.21 and openspec on your PATH. uv run python -m osf doctor checks the host and names anything missing.

From the root of the repository:

uv sync                                   # Python dependencies
(cd ui && npm ci && npm run build)        # build the web UI into ui/dist, which osfd serves

export OSF_ROOT=$PWD/.dogfood OSF_STATE_DIR=$PWD/.dogfood/state   # database, repo copies, run worktrees
export OSF_SANDBOX=none                   # no systemd sandbox on a laptop
export OSF_GATE_URL=                      # no inference meter: agents talk to the model directly
export OSF_UPSTREAM_URL=http://<model-host>:8090/v1   # your OpenAI-compatible model server

uv run python -m osf migrate              # create or upgrade the database (always explicit)
uv run python -m osf serve                # start osfd, the Braid server

Then open http://127.0.0.1:8710. The API is on the same address. curl http://127.0.0.1:8710/api/status says "ready" when the server is idle, "running" while steps run, and "down" when it cannot reach the model server.

• Forgejo. Issues and pull requests use https://forgejo.underthere.xyz with the API token in ~/.config/opencode/forgejo-token. Point elsewhere with OSF_FORGEJO_URL and OSF_FORGEJO_TOKEN_FILE.
• Model server. Change it later from the settings page (the ⚙ in the header, or g s).
• Keyboard. The console is keyboard-driven: ? lists every shortcut.
• Another port. Use OSF_PORT=9000, or OSF_PORT_OFFSET=100 to shift every port so a second copy runs at http://127.0.0.1:8810.
• Stop it. Kill whatever owns the port: kill $(lsof -t -nP -iTCP:8710 -sTCP:LISTEN).
• No GPU? Run ./tools/demo.sh up. It starts osfd against a fake model at the same http://127.0.0.1:8710, enough to try the UI, and ./tools/demo.sh down stops it. The fake model is scripted for exploring only, so a run there stops at the proposal.

More detail, including the full demo, is in the guide.

Production

Braid runs in production at http://openspecflow.internal.underthere.xyz, an internal tool reached on the LAN or over the VPN. It is a container stack on the openspecflow VM, managed by Portainer. Every push to main rebuilds the image, pushes it to the Forgejo registry, waits for busy steps to finish (running, or waiting on an agent's question) for up to an hour, and redeploys. curl http://openspecflow.internal.underthere.xyz/api/status reports the build it is serving as commit.

The runbook covers setup, redeploys, rollback and logs: deploy/README.md.

Acknowledgements

Braid stands on the shoulders of these open-source projects!

OpenSpec	Spec-driven change format; openspec validate checks every proposal
opencode	The agent runtime; each step drives an opencode serve session
Qwen	The open-weight model family doing the thinking
vLLM	Serves the model on local hardware
Forgejo	Issues in, pull requests out
Starlette · Uvicorn	The osfd web server and API
SQLite	The single append-only run log
Playwright	The browser the judge opens a UI change in, and the console's own browser tests
React · Vite · Tailwind CSS · virtua	The web UI

Learn more

• Guide: running it, prerequisites, the keyboard, the pipelines, real-run notes, layout
• Deploy runbook: the production stack, redeploys, rollback and logs
• Design: the design of record (read §0a first)
• Contract: module ownership and core rules

License

MIT