Agents propose large structural changes. Humans review walls of text. WorkBraid solves this by serializing architecture state into visual diagrams backed by Git, so both parties can see what changed without parsing 400 lines of diff output.
The tool runs locally and exposes two interfaces: a CLI for direct invocation and an MCP server for agent integration. When an agent proposes a change, WorkBraid generates a visual diff showing before and after states. The human reviews the diagram, approves or rejects, and the tool commits the change to Git with full history.
The author built WorkBraid because text-heavy diffs fail for architectural changes. When an agent suggests splitting a monolith into three services, the code diff shows file additions and deletions. The diagram shows service boundaries, data flows, and dependency changes in one frame.
This matters for human-agent collaboration. Agents excel at proposing structural refactors but lack the context to know if a change breaks deployment assumptions or violates team conventions. A visual review layer lets humans catch those issues before merge.
WorkBraid stores architecture state as structured data in a Git repository. Each diagram is a serialized object graph with nodes (services, databases, queues) and edges (API calls, data flows, event subscriptions). The tool renders this graph into a visual editor and diffs it like source code.
The MCP server exposes three core operations:
The CLI mirrors these operations for direct human use. Both interfaces write to the same Git-backed store, so changes from either path are versioned and reviewable.
WorkBraid serializes diagrams as JSON with semantic annotations. A service node includes name, type, dependencies, and metadata like deployment target or scaling policy. An edge includes source, destination, protocol, and data schema references.
When an agent proposes a change, it submits a patch object:
{
"operation": "add_node",
"node": {
"id": "payment-service",
"type": "service",
"dependencies": ["user-db", "event-bus"],
"metadata": {
"language": "go",
"deployment": "k8s"
}
}
}
WorkBraid applies the patch, generates a visual diff, and writes the new state to Git. The commit message includes both the JSON patch and a rendered diagram URL for review tools.
Conflicts arise when a human and an agent modify the same component. WorkBraid detects conflicts at the node or edge level, not the file level. If both parties rename a service, the tool flags the conflict and blocks the merge.
The resolution flow:
This is simpler than traditional merge conflict resolution because the conflict surface is smaller. A service node has five properties. A source file has hundreds of lines.
An agent using the MCP server follows this pattern:
get_current_state to retrieve the architecture graphpropose_change with a structured patchlist_pending_proposals to check review status
The agent never touches the visual layer. It operates on structured data and trusts WorkBraid to handle rendering and review UX.
A human using the CLI or web UI:
The human never writes JSON patches. They interact with diagrams and let WorkBraid serialize the changes.
| Aspect | Benefit | Cost |
|---|---|---|
| Visual diffs | Faster review for structural changes | Requires learning diagram semantics |
| Git-backed state | Full version history and rollback | Merge conflicts on concurrent edits |
| MCP interface | Agents propose changes without custom code | Limited to supported diagram types |
| Local-first | No cloud dependency or data leakage | No built-in collaboration features |
| Structured patches | Precise conflict detection | Agents must generate valid JSON |
WorkBraid does not yet expose metrics on proposal acceptance rates, review latency, or conflict frequency. These signals matter for tuning agent behavior. If 80% of proposals are rejected, the agent's change heuristics need adjustment.
The tool also lacks audit logs for who approved what and when. In a team setting, you need to know if a junior engineer approved a breaking change or if an agent bypassed review through a misconfigured policy.
WorkBraid runs as a local process. The CLI is a single binary. The MCP server is a long-running process that listens for agent requests. Both read and write to a Git repository on disk.
For team use, you point multiple WorkBraid instances at a shared Git remote. Each developer runs their own instance. Agents connect to the MCP server via localhost or a network socket. The Git remote handles synchronization and conflict detection.
This shape avoids centralized infrastructure but creates coordination overhead. If two agents propose conflicting changes simultaneously, both proposals land in Git and require manual resolution.
Diagram drift: If developers bypass WorkBraid and modify architecture manually, the diagram state diverges from reality. The tool has no enforcement mechanism to prevent this.
Agent hallucination: An agent might propose a valid JSON patch that represents an invalid architecture (circular dependencies, missing required services). WorkBraid validates JSON structure but not architectural semantics.
Review bottleneck: If agents propose changes faster than humans can review, the queue grows unbounded. The tool needs rate limiting or auto-rejection policies.
Merge storm: In a large team, concurrent proposals from multiple agents create a merge conflict cascade. Git handles this poorly when the conflict surface is a shared architecture graph.
Use WorkBraid when:
Avoid WorkBraid when:
The tool is early-stage. Expect rough edges around conflict resolution, limited diagram types, and missing observability. But the core idea is sound: agents and humans collaborate better when they share a visual language for architectural change.