Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
// Where to drop a NEW node when there is no cursor to place it at (the kanban board's "+ New
// session", the dock's add menu, the command palette). Those all fell back to the view center, so
// every node created that way piled up on the same spot — switch to the canvas and you'd find a
// stack of overlapping nodes. `freeSpot` instead finds the nearest empty position.
//
// `slotBelowSource` is the same problem for a node an AGENT opens (canvas-control's open/show
// verbs), where there IS an anchor — the agent's own node — and the layout should read as "hanging
// off that conversation".
import { rootPositionIn, type PlacedNode } from './projectOpen'
export interface Box {
x: number
y: number
w: number
h: number
}
/** How far a bounded placement steps down-right off a node whose top-left it would share (#1140):
* enough to leave that node's header row showing above the new one. */
export const CASCADE_STEP = 32
const CASCADE_MAX_HOPS = 64
/** `p`, moved down-right by `CASCADE_STEP` until no box in `existing` starts within a step of it. */
function cascadeOff(existing: Box[], p: { x: number; y: number }): { x: number; y: number } {
let { x, y } = p
for (
let hop = 0;
hop < CASCADE_MAX_HOPS &&
existing.some((b) => Math.abs(b.x - x) < CASCADE_STEP && Math.abs(b.y - y) < CASCADE_STEP);
hop++
) {
x += CASCADE_STEP
y += CASCADE_STEP
}
return { x, y }
}
/**
* The nearest position (to `preferred`) where a `size` box does not overlap any of `existing`,
* searched outward on a grid stepped by the node size. Returns `preferred` unchanged when it's
* already clear (so a lone node / an empty canvas keeps the centered placement). Pure + testable.
* `preferred` and the answer are TOP-LEFT corners.
*
* `gap` is the minimum breathing room kept between boxes. The ring search is capped so a pathological
* canvas can never loop forever — past the cap it gives up and returns `preferred` (overlap is a far
* lesser evil than a hang).
*
* `bounds` (issue #1140) keeps the answer inside a rectangle — the visible canvas — so a node made
* from a shortcut never lands somewhere the user cannot see. Inside it the search runs on a half-step
* grid (a view is only a few nodes wide), and when nothing in view is clear it takes the in-view
* spot covered LEAST, nearest first: a busy view gets a visible, partly overlapping node rather than
* a clear one off screen. The search starts from `preferred` pulled inside `bounds` (a pinned panel
* can push the view centre's box past the visible edge), and a node too big for `bounds` at all
* (zoomed in past the node's size) stays at `preferred`.
*
* Whatever the bounded branch answers is CASCADED off any node whose top-left it would share
* (`CASCADE_STEP` down-right per hit, like stacked windows): a view under about two node-widths has
* no other in-view cell, and without this every node made in a row landed exactly on the last one —
* invisible, the very pile this function exists to prevent.
*/
export function freeSpot(
existing: Box[],
preferred: { x: number; y: number },
size: { w: number; h: number },
gap = 28,
bounds?: Box
): { x: number; y: number } {
const clear = (x: number, y: number): boolean =>
!existing.some(
(b) =>
x < b.x + b.w + gap &&
x + size.w + gap > b.x &&
y < b.y + b.h + gap &&
y + size.h + gap > b.y
)
if (clear(preferred.x, preferred.y)) return preferred
if (bounds) {
// "Does it fit at all" is size against bounds, never where the centred box happens to sit.
if (size.w > bounds.w || size.h > bounds.h) return cascadeOff(existing, preferred)
const inside = (x: number, y: number): boolean =>
x >= bounds.x && y >= bounds.y && x + size.w <= bounds.x + bounds.w && y + size.h <= bounds.y + bounds.h
const start = {
x: Math.min(Math.max(preferred.x, bounds.x), bounds.x + bounds.w - size.w),
y: Math.min(Math.max(preferred.y, bounds.y), bounds.y + bounds.h - size.h)
}
if (clear(start.x, start.y)) return start
const covered = (x: number, y: number): number =>
existing.reduce((sum, b) => {
const w = Math.min(x + size.w, b.x + b.w) - Math.max(x, b.x)
const h = Math.min(y + size.h, b.y + b.h) - Math.max(y, b.y)
return w > 0 && h > 0 ? sum + w * h : sum
}, 0)
const sx = (size.w + gap) / 2
const sy = (size.h + gap) / 2
const rings = Math.min(200, Math.ceil(Math.max(bounds.w / sx, bounds.h / sy)) + 1)
let best = { x: start.x, y: start.y, area: covered(start.x, start.y) }
for (let ring = 1; ring <= rings; ring++) {
for (let dy = -ring; dy <= ring; dy++) {
for (let dx = -ring; dx <= ring; dx++) {
if (Math.max(Math.abs(dx), Math.abs(dy)) !== ring) continue // perimeter only
const x = start.x + dx * sx
const y = start.y + dy * sy
if (!inside(x, y)) continue
if (clear(x, y)) return { x, y }
const area = covered(x, y)
if (area < best.area) best = { x, y, area }
}
}
}
return cascadeOff(existing, { x: best.x, y: best.y })
}
const stepX = size.w + gap
const stepY = size.h + gap
// Expanding square rings around `preferred`; within a ring, walk the perimeter and take the first
// clear cell. Nearest-first keeps new nodes close to where the user is looking.
for (let ring = 1; ring <= 60; ring++) {
for (let dy = -ring; dy <= ring; dy++) {
for (let dx = -ring; dx <= ring; dx++) {
if (Math.max(Math.abs(dx), Math.abs(dy)) !== ring) continue // perimeter only
const x = preferred.x + dx * stepX
const y = preferred.y + dy * stepY
if (clear(x, y)) return { x, y }
}
}
}
return preferred
}
/**
* `freeSpot` in the terms the node factories speak: a CENTRE in, a CENTRE out (`placeAt` turns a
* centre into the top-left by subtracting half the size). Issue #1140: `emptyNodePos` used to hand
* the view centre to `freeSpot` AS a top-left and then give the answer to the factories AS a centre,
* so every overlap check was made half a node away from where the node actually landed.
*/
export function emptySpotCenter(
existing: Box[],
view: Box | undefined,
center: { x: number; y: number },
size: { w: number; h: number },
gap = 28
): { x: number; y: number } {
const topLeft = { x: center.x - size.w / 2, y: center.y - size.h / 2 }
const at = freeSpot(existing, topLeft, size, gap, view)
return at === topLeft ? center : { x: at.x + size.w / 2, y: at.y + size.h / 2 }
}
/**
* Where a node an AGENT opens lands (canvas-control's `open-*` / `show-*` verbs). Returns a
* TOP-LEFT point in root space.
*
* The old rule was a fixed point under the source, fanned right by 460 px per node of the SAME
* call, with no look at the canvas. So the ordinary orchestration shape — one `open-claude` per
* worktree, each a separate call with count 1 — put every session on exactly one spot, and even a
* single `--count 3` overlapped itself (a default node is 640 px wide).
*
* Now: a grid under the source, left-aligned to it, filled row by row (`cols` per row), taking the
* first cell that keeps `gap` clear of everything in `occupied`. The cell is tested AFTER `snap`,
* so grid rounding cannot slide a node onto a neighbour after the check passed. `occupied` must be
* root-space and must include every node placed earlier in the same batch. Past the search cap it
* drops below everything, which is clear by construction — overlap is never the fallback.
*/
export function slotBelowSource(
occupied: readonly Box[],
source: Box,
size: { w: number; h: number },
opts: {
gap?: number
cols?: number
snap?: (p: { x: number; y: number }) => { x: number; y: number }
} = {}
): { x: number; y: number } {
const gap = opts.gap ?? 40
const cols = Math.max(1, Math.floor(opts.cols ?? 4))
const snap = opts.snap ?? ((p) => p)
const clear = (p: { x: number; y: number }): boolean =>
!occupied.some(
(b) =>
p.x < b.x + b.w + gap &&
p.x + size.w + gap > b.x &&
p.y < b.y + b.h + gap &&
p.y + size.h + gap > b.y
)
// 80 px under the source: the room the lineage rope has always had.
const top = source.y + source.h + 80
for (let row = 0; row < 200; row++) {
for (let col = 0; col < cols; col++) {
const p = snap({ x: source.x + col * (size.w + gap), y: top + row * (size.h + gap) })
if (clear(p)) return p
}
}
const bottom = occupied.reduce((m, b) => Math.max(m, b.y + b.h + gap), top)
// Snap can round up to half a cell back toward the box above; a whole extra gap absorbs it.
return snap({ x: source.x, y: bottom + gap })
}
/** A node as the live canvas (React Flow, with `measured`) or the serialized store (`size`) holds
* it — enough to place something next to it. */
export interface PlaceableNode extends PlacedNode {
id: string
measured?: { width?: number; height?: number }
}
const DEFAULT_W = 600
const DEFAULT_H = 400
const boxOf = (n: PlaceableNode, at: { x: number; y: number }): Box => ({
x: at.x,
y: at.y,
w: n.measured?.width ?? n.size?.width ?? (n.width as number | undefined) ?? DEFAULT_W,
h: n.measured?.height ?? n.size?.height ?? (n.height as number | undefined) ?? DEFAULT_H
})
/**
* `slotBelowSource` over a project's node array: resolves every node (and the source) to ROOT
* space, and leaves out the frames that CONTAIN the source — the opened node is parented into the
* source's frame, so that frame is where it belongs, not an obstacle. Any other frame is one: a
* top-level node drawn over a frame reads as inside it while it is not. `extra` is what this batch
* (or a racing call) already placed and the array does not show yet. `undefined` when the source
* is not in `nodes`.
*/
export function placeBelowSource(
nodes: readonly PlaceableNode[],
sourceId: string,
size: { w: number; h: number },
opts: { extra?: readonly Box[]; snapGrid?: number } = {}
): { x: number; y: number } | undefined {
const src = nodes.find((n) => n.id === sourceId)
if (!src) return undefined
const ancestors = new Set<string>()
const byId = new Map(nodes.map((n) => [n.id, n]))
for (let p = src.parentId; p && !ancestors.has(p); p = byId.get(p)?.parentId) ancestors.add(p)
const occupied = nodes
.filter((n) => !ancestors.has(n.id))
.map((n) => boxOf(n, rootPositionIn(nodes, n)))
const g = opts.snapGrid ?? 0
return slotBelowSource(
[...occupied, ...(opts.extra ?? [])],
boxOf(src, rootPositionIn(nodes, src)),
size,
g > 0
? { snap: (p) => ({ x: Math.round(p.x / g) * g + 0, y: Math.round(p.y / g) * g + 0 }) }
: {}
)
}
/**
* A box an open has taken but the node array may not show yet: `setNodes` commits on the next
* render and the cold path's snapshot is read before its awaits, so two opens racing each other
* (an agent firing `open-claude … &` per worktree) would otherwise both see the same empty cell.
*/
export interface PlacementClaim {
projectId: string
id: string
box: Box
at: number
}
/** Long enough to outlive any render/IPC lag, short enough that a deleted node's cell frees up. */
export const PLACEMENT_CLAIM_TTL_MS = 10_000
export function pruneClaims(claims: readonly PlacementClaim[], now: number): PlacementClaim[] {
return claims.filter((c) => now - c.at < PLACEMENT_CLAIM_TTL_MS)
}
/** The claims that still answer for a cell: same project, still young, and not yet in the array —
* once the node is present its REAL box (which the user may have moved) speaks for it. */
export function pendingClaimBoxes(
claims: readonly PlacementClaim[],
projectId: string,
presentIds: ReadonlySet<string>,
now: number
): Box[] {
return claims
.filter((c) => c.projectId === projectId && now - c.at < PLACEMENT_CLAIM_TTL_MS && !presentIds.has(c.id))
.map((c) => c.box)
}