WorkBraid: Visual Architecture Diffs for Agent-Proposed Code Changes

WorkBraid is a tool that helps humans and agents collaborate on large architectural changes by converting code diffs into visual diagrams. When an agent suggests a change, WorkBraid generates a visual representation showing the before and after states, which makes it easier for humans to review and approve or reject the modification. The tool runs locally and provides two interfaces: a command-line interface (CLI) for direct interaction and a master control protocol (MCP) server for integration with agents.

The core concept behind WorkBraid is to store architecture state as structured data in a Git repository. This allows for version control and easy retrieval of the current architecture graph. Each diagram is represented as a serialized object graph, consisting of nodes (services, databases, queues) and edges (API calls, data flows, event subscriptions). The tool renders this graph into a visual editor and applies diffs like source code changes.

WorkBraid offers three core operations for agents: proposing changes, retrieving the current architecture state, and querying pending proposals. These operations are mirrored through the CLI for human interaction. When an agent proposes a change, it submits a patch object containing information about the operation (add node, remove edge, modify property) and the specific details of the proposed change.

WorkBraid applies this patch, generates a visual diff, and writes the updated state to the Git repository. The commit message includes both the JSON patch and a URL to the rendered diagram for review.

In cases where both humans and agents modify the same component, WorkBraid detects conflicts at the node or edge level, rather than the file level. If there is a conflict, the tool generates a three-way diff (base, human, agent), and the human must review the visual editor to make a decision. The tool commits the resolved state, simplifying the conflict resolution process compared to traditional methods.

Agents using WorkBraid follow a specific workflow: they retrieve the architecture graph using the `get_current_state` operation, analyze the graph to identify a proposed change, call `propose_change` with a structured patch, and then poll `list_pending_proposals` to check the review status. If the proposal is approved, it is automatically committed to the repository, without any direct interaction with the visual layer.

Humans, on the other hand, use the CLI or web UI to interact with WorkBraid. They open the visual editor to see the current architecture, receive notifications of pending agent proposals, review the visual diff showing the before and after states, and then approve, reject, or request modifications. WorkBraid handles the serialization of these changes based on the human's actions.

While WorkBraid offers several benefits, such as faster review for structural changes and full version history for rollback purposes, it comes with some trade-offs. The tool requires users to learn the semantics of the diagram representation, there is no built-in collaboration feature, and agents are limited to using supported diagram types. Additionally, there are gaps in observability, such as the lack of metrics on proposal acceptance rates and review latency, which may require adjustments to agent change heuristics.

WorkBraid operates as a local process, with the CLI being a single binary and the MCP server being a long-running service that listens for agent requests. Both the CLI and MCP server read and write to a Git repository on disk. For team use, multiple WorkBraid instances can be pointed at a shared Git remote, allowing each developer to run their own instance and connecting to the MCP server via localhost or a network socket.

This local-first approach avoids centralized infrastructure but introduces coordination overhead, as simultaneous conflicting proposals from different agents will need manual resolution.