Workspace Graph

An infinite-canvas visualization of your entire project topology — every Lane, PR, branch, and dependency relationship, with live merge simulation.

Overview

The Workspace Graph is ADE’s spatial view of your project — every Lane, PR, branch, and dependency relationship laid out by React Flow + ELK.js and updated in real time. It shows how everything connects: which lanes are stacked, which branches have open PRs, where conflicts are likely, and how far each line of work has drifted.

Topology at a Glance

See every lane, PR, and branch relationship in one view. Hierarchical layout auto-arranges nodes based on branch ancestry.

Merge Simulation

Run a background merge simulation using git merge-tree. Predicted conflicts overlay as edge annotations before you touch a single branch.

Drag-to-Reparent

Drag a lane node onto another to change its base branch. ADE previews the rebase before committing.

---

Opening the Graph

Click the Graph icon in the left sidebar. The graph opens as a full-screen tab in the main panel.

The graph updates live. If an agent commits code or a PR changes review status while the graph is open, the relevant node refreshes automatically — no manual reload needed.

---

Understanding Nodes

Every entity in your project is represented as a node on the canvas.

Lane Nodes

Lane nodes are the primary building blocks of the graph. Each node displays:

• Lane name and branch name
• Status badge: color-coded by current state
• Agent activity indicator: spinning pulse when an agent is actively working
• Pack freshness: a small indicator showing how fresh the lane’s context pack is
• Port allocation: the port number assigned to this lane (e.g., :3001) and its preview URL

Status colors:

Color	Status	Meaning
Green	Idle	Lane is clean and ready — no active agent, no conflicts
Blue	Active	An agent is currently working in this lane
Orange	Conflict	Overlap with another lane’s changes detected
Red	Blocked	Lane is blocked — merge conflict, failing CI, or intervention required
Gray	Archived	Lane has been archived and is read-only

PR Nodes

Each lane with an open pull request has a PR node connected to it. PR nodes show:

• PR number and title (truncated)
• Review status: Draft, Open, Approved, Changes Requested, Needs Review
• CI check rollup (all green, some failing, or pending)

Clicking a PR node opens the PR detail in the Inspector panel without leaving the graph.

Branch Nodes

Orphaned branches — branches that exist in your repository but are not registered as a lane in ADE — appear as lighter-weight branch nodes. These are useful for importing stale remote branches or seeing the full repository topology.

Right-click a branch node to convert it into a full Lane.

---

Understanding Edges

Edges represent relationships between nodes.

• Dependency edges: Lane A’s base is Lane B — A is stacked on top of B. Shown as a solid directional line.
• PR target edges: A lane’s PR targets the main branch (or another lane’s branch). Shown as a dashed line connecting the PR node to its target.
• Merge simulation overlays: After running a simulation, edges gain annotation badges showing predicted merge outcome, conflict count, and risk level.

---

View Modes

The toolbar at the top of the graph provides three view modes. Switch between them without losing your canvas position.

Lane View

The default view. Every node shows its lane status, agent activity pulse, and pack freshness indicator. Edges show dependency relationships.

This mode is optimized for day-to-day orchestration: you see which lanes are active, which need attention, and how work is stacked.

PR View

PR view emphasizes pull request status across the graph. Lane nodes are de-emphasized in favor of PR nodes, which grow larger and show detailed review status.

Use PR view during code review cycles when you need to see at a glance which PRs are approved and ready to merge, which need re-review, and which are still in draft.

PR status colors in this mode:

• Green: Approved and CI passing
• Yellow: Approved but CI pending or failing
• Blue: Open, awaiting review
• Gray: Draft — not yet ready for review
• Red: Changes requested

Conflict Heat Map

Heat map view colors every node and edge by conflict risk severity, computed from ADE’s overlap analysis engine.

Color	Risk Level	Meaning
Green	Safe	No overlapping file changes with other branches
Yellow	Warning	Some file overlap detected; conflicts possible
Orange	Moderate	Significant overlap; likely conflicts on merge
Red	High Risk	Direct conflicting edits to the same lines

This mode is most useful before a release window when you need to decide merge order and spot integration risks before they become blockers.

---

Merge Simulation

The merge simulation feature predicts what would happen if each lane’s branch were merged into the base branch, in sequence. ADE uses git merge-tree under the hood — the same algorithm Git uses for real merges, but without touching any branch on disk.

Running a Simulation

1. Click 'Simulate Merges'

   Click the Simulate Merges button in the graph toolbar. ADE queues merge simulation jobs for all visible lanes.

2. Wait for results

   The simulation runs in the background. Individual edge annotations appear as each lane’s simulation completes — you do not need to wait for all lanes. Typically 2-5 seconds per lane depending on diff size.

3. Read the annotations

   Each edge connecting a lane to its base gains an annotation badge:

   • Clean: The merge would succeed with no conflicts
   • N conflicts: The number of conflicting hunks detected
   • Diverged: The branch has diverged significantly; a manual review is recommended
4. Inspect details

   Click any edge annotation badge to open a conflict detail drawer. It shows the conflicting files, the specific hunks in contention, and a side-by-side preview of both versions.

Merge simulation results reflect the state of branches at the time of the simulation run. They go stale as agents commit new code. Re-run the simulation before making merge decisions if significant work has been done since the last run. The timestamp in the toolbar shows when the last simulation was run.

Simulating a Subset

To simulate only selected lanes rather than the entire graph, Shift+click to select a set of lane nodes first, then click Simulate Merges. ADE runs the simulation only on the selected set — useful for large projects where a full simulation takes longer.

---

Drag-to-Reparent

You can change a lane’s base branch directly in the graph by dragging one lane node onto another.

1. Start the drag

   Click and hold a lane node, then slowly drag it toward the target lane (the new base you want). After a brief pause, the node enters drag-reparent mode — a blue outline appears on valid drop targets.

2. Preview the rebase

   Drop the node onto the target lane. Before committing anything, ADE shows a Rebase Preview overlay:

   • The new parent–child relationship as it would appear
   • A summary of commits that will be rebased
   • Any predicted conflicts in the rebase (from git merge-tree)
3. Confirm or cancel

   Click Confirm Rebase to proceed. ADE runs git rebase --onto <new-base> in the lane’s worktree. Click Cancel to discard the change — no branches are touched.

4. Graph updates

   After a successful rebase, the graph re-runs ELK layout and animates nodes to their new positions. The edge topology reflects the new dependency.

Drag-to-reparent is a destructive git operation (rebase rewrites history). If the lane’s branch has already been pushed to a remote, the rebase will require a force-push. ADE warns you if this is the case before confirming.

---

Batch Operations

Select multiple nodes to perform bulk operations across lanes.

Selecting multiple nodes:

• Shift+click: Add individual nodes to the selection
• Drag-select: Click and drag on empty canvas space to draw a selection rectangle

Once nodes are selected, the batch operations toolbar appears at the bottom of the screen:

Operation	Description
Archive Selected	Archive all selected lanes (with a single confirmation dialog)
Simulate Merges	Run merge simulation on selected lanes only
Export Packs	Export context packs for all selected lanes as a .zip
Run Preflight	Run worker run preflight checks across all selected lanes

---

Navigation and Canvas Controls

Zoom

Scroll (trackpad pinch or mouse wheel) to zoom in and out. Use the graph zoom controls to zoom in, zoom out, or fit the graph.

Pan

Click and drag on empty canvas space to pan. On a trackpad, two-finger scroll pans the canvas without zooming.

Mini-map

The mini-map in the bottom-right corner shows the full graph overview. Click anywhere on the mini-map to jump to that region. Click the mini-map header to collapse it.

Node Click

Clicking a lane node opens that lane’s detail in the Inspector panel without leaving the graph tab. Double-click to navigate fully into the lane.

Node Hover Tooltips

Hovering over a lane node for 500ms shows a tooltip with:

• Branch name and last commit message
• Last commit author and timestamp
• Agent status (idle / running / completed)
• Conflict risk score (0–100)
• Pack freshness age

---

Graph Layout

ADE uses ELK.js (Eclipse Layout Kernel) to automatically arrange nodes in a hierarchical tree based on branch relationships. The main branch sits at the top; lanes forked from it appear below; lanes stacked on other lanes appear further down the hierarchy.

Manual repositioning: Drag any node to a custom position. Node positions are persisted per-project — your layout survives restarts. To reset to the auto-layout, click Reset Layout in the graph toolbar.

ELK layout runs automatically when new lanes are added or when lanes are archived. If you have manually positioned nodes, ADE attempts to preserve your positions and only moves newly-added nodes into available space.

---

Keyboard Shortcuts

Shortcut	Action
Shift+Enter	Open the context menu for the selected lane
Arrow Up / Arrow Left	Move selection to the selected lane’s parent
Arrow Down / Arrow Right	Move selection to the selected lane’s first child
Escape	Close open menus or panels
Cmd++ / Cmd+-	Zoom in / zoom out

---

Edge Cases and Large Projects

Very large projects (50+ lanes)

With 50 or more lanes, ELK layout can take 2-3 seconds to compute. ADE shows a “Recalculating layout…” indicator during this time. For very large graphs, consider using lane groups (configure in ade.yaml) to cluster related lanes and reduce visual noise.

Merge simulation on 50+ lanes runs all jobs in parallel but may take 30-60 seconds for large repositories with deep histories.

Disconnected branches

Branches with no relationship to your base branch (e.g., orphan branches like gh-pages) appear as isolated nodes in the upper-right quadrant of the graph. They are not included in merge simulations by default.

Simulation on branches with merge commits

git merge-tree works best on linear histories. On branches with merge commits, ADE uses the branch tip as the simulation target. The simulation may report false negatives (fewer conflicts than will actually occur) in complex octopus-merge scenarios.

Graph not updating

The graph subscribes to live IPC events from the main process. If it appears stale, use the visible refresh controls in the graph surface. If the issue persists, check that the ADE main process is running and the IPC bridge is healthy (visible in Settings → Diagnostics).

---

Related Pages

Lanes

Understand lane types, status, and lifecycle before diving into the graph.

Conflicts

Deep dive into ADE’s conflict detection and resolution tools.

Pull Requests

Manage PRs from within ADE, including review status and merge workflows.

Workers

Launch multi-step AI worker runs across lanes and track them from the graph.