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. Why This Exists 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. Architecture Contract 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: propose_change: Agent submits a structured diff (add node, remove edge, modify property) get_current_state: Agent retrieves the current architecture graph list_pending_proposals: Agent or human queries open change requests 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. State Serialization 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. Merge Conflict Handling 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: WorkBraid detects overlapping changes Tool generates a three-way diff (base, human, agent) Human reviews in the visual editor Human selects winning change or merges manually Tool commits the resolved state 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. Integration Patterns Agent Workflow An agent using the MCP server follows this pattern: Call get_current_state to retrieve the architecture graph Analyze the graph and identify a proposed change Call propose_change with a structured patch Poll list_pending_proposals to check review status If approved, the change is committed automatically The agent never touches the visual layer. It operates on structured data and trusts WorkBraid to handle rendering and review UX. Human Workflow A human using the CLI or web UI: Open the visual editor to see current architecture Receive a notification of a pending agent proposal Review the visual diff showing before and after states Approve, reject, or request modifications WorkBraid commits or discards the change The human never writes JSON patches. They interact with diagrams and let WorkBraid serialize the changes. Trade-offs 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 Observability Gaps 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. Deployment Shape 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. Likely Failure Modes 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. Technical Verdict Use WorkBraid when: You work with agents that propose large structural changes Your team reviews architecture visually, not in text You need Git-backed versioning for architectural decisions You want a local-first tool with no cloud dependency Avoid WorkBraid when: Your architecture changes are small and localized Your team lacks visual review discipline You need real-time collaboration across distributed teams You require enforcement of architectural constraints beyond JSON schema validation 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. Source Links WorkBraid GitHub Repository Show HN Discussion