WorkBraid

Important

The implementation in this repository is AI-generated.

WorkBraid is an experiment in building software primarily through AI coding agents under human direction. It is early-stage software and should be reviewed accordingly. Contributions and reviews from humans and agents are both welcome.

WorkBraid is a local-first, graph-first workspace for planning, executing, reviewing, and auditing AI-assisted software development.

It models proposals, decisions, work, dependencies, agent runs, and reviews as a connected graph. The long-term goal is to let that graph coordinate large software projects while keeping humans able to inspect, approve, interrupt, and redirect the work.

WorkBraid was inspired in part by Herdr, which provides persistent local sessions, agent processes, terminals, and worktrees. WorkBraid is a separate standalone application that uses Herdr as its first supported execution runtime.

Status

WorkBraid currently provides an early usable vertical slice:

• Graph-based project planning with arbitrary hierarchy and typed relationships
• Readiness and blocker calculation with execution-cycle detection
• Local SQLite persistence and immutable audit history
• Manual dispatch through Herdr
• Layered project, node, and one-run execution profiles with immutable run provenance
• Project-wide retained Sessions & cleanup view with explicit session-only, worktree, bulk, retry, and dirty-force paths
• Multiple run attempts and run-specific human review
• Optional separate agent reviewer sessions with exact-artifact advisory verdicts; human review remains final
• Conflict-aware Markdown import and export
• A browser UI served from a single Go executable

The project is not yet ready for unattended or security-sensitive use.

Run

Requirements:

• Go 1.25+
• Node.js 22+ when rebuilding the frontend
• Herdr 0.8.0, optionally, for isolated interactive agent dispatch

npm install --prefix frontend
npm run build --prefix frontend
go build -o workbraid ./cmd/workbraid
./workbraid

Open http://127.0.0.1:8427.

WorkBraid binds only to loopback by default and stores its database at .workbraid/workbraid.db. Start it with --no-runtime when Herdr is unavailable.

Export the project graph as Markdown:

./workbraid export

Import safe Markdown-only changes with ./workbraid import. Divergent changes stop with a conflict; choose a side explicitly with --conflict workbraid or --conflict external. Files are synchronized beneath the project's .workbraid/ directory.

Remote access

Keep WorkBraid bound to loopback and use an SSH tunnel:

ssh -L 8427:127.0.0.1:8427 developer@workstation

Then open http://127.0.0.1:8427 locally.

WorkBraid does not currently implement authentication. Do not expose it directly on a non-loopback interface.

Test

go test ./...
go test -race ./...
go vet ./...
npm run format:check --prefix frontend
npm run test:run --prefix frontend
npm run build --prefix frontend
npm run check:bundle --prefix frontend
PLAYWRIGHT_BROWSERS_PATH=$PWD/.cache/ms-playwright \
  npx --prefix frontend playwright test --config e2e/playwright.config.ts
PLAYWRIGHT_BROWSERS_PATH=$PWD/.cache/ms-playwright \
  npx --prefix frontend playwright test --config e2e/orchestrator-chat.config.ts

Tests use real temporary SQLite databases and real temporary directories. End-to-end tests run the production server and frontend against a controlled fake Herdr runtime.

The installed Herdr 0.8 terminal and prompt capability contract is opt-in and read-only:

WORKBRAID_REAL_HERDR=1 go test ./internal/runtime/herdr -run RealHerdr

The existing real-Herdr browser smoke test also verifies that terminal viewing starts as a non-interactive mirror; it never takes control automatically.

See:

• Architecture
• Markdown format
• WorkBraid development graph

License

WorkBraid is licensed under the Apache License 2.0.