TermCanvas – spatial terminal canvas for AI agent orchestration on macOS

TermCanvas is a desktop application for macOS built on Electron that lets developers arrange real terminal sessions on an infinite canvas with pan and zoom. It is designed for teams and individuals who juggle multiple repositories, shells, AI agents, and long-running tasks and want a more spatial alternative to tabs or split panes.

At its core, TermCanvas provides real interactive shell terminals rendered with xterm.js, draggable and resizable on the canvas. Users can double-click empty space to create a terminal, drag to move around, and use the mouse wheel to zoom. Terminals can be renamed, maximized, restored, or closed; the app supports multiple project-bound canvases for separate work contexts, a workspace drawer for browsing imported folders and previewing files side-by-side with terminals, and app-session restore across relaunches. Keyboard shortcuts include Cmd+B to toggle the file drawer, Cmd+M to maximize or restore a terminal, Cmd+L to close the file preview, and Esc to exit preview or maximize mode. Canvas state—node positions, viewport, workspaces, preview state—is saved automatically, and when tmux is available, closing the app detaches from live shells instead of killing them, preserving sessions for relaunch.

The standout feature is its integration with agentmux, a peer-to-peer agent graph manager bundled into packaged apps. When a developer opens a terminal on the canvas, it is registered as a root agent in the graph and receives environment variables (AGENTMUX_PROJECT, AGENTMUX_AGENT_NAME, AGENTMUX_BIN, and related vars) from birth. Any agent framework started inside (Claude Code, Codex, OpenCode, or custom agents) inherits full graph context automatically. Agents can spawn child agents (via `agentmux worker` or `agentmux child`) or connect to peers (via `agentmux connect`), and the canvas renders both relationships as edges with directional arrows. There is no fixed hierarchy—any agent can spawn children or connect to any other. Managed agent terminals show a node badge indicating "Agent (in the graph)" or "Solo (plain terminal, not yet adopted)." Delegation happens through the `ask` command, which blocks until the target agent finishes and returns output, enabling RPC-style calls like `result=$(agentmux ask <agent> "...")`. Agents spawned on an AI harness receive an automatic [TermCanvas] briefing as their first message, including identity, project, spawner, and how to use neighbors/ask/check/child; users can pass `--no-briefing` to opt out.

The app works without installing an agent skill, but developers can install one to teach coding agents how to operate the live agent tree. Packaged apps offer a one-click installer; alternatively, users can run `npx skills add lout33/termcanvas --skill agentmux -g -a codex -a claude-code -a opencode` to install the public skill from the repository. The skill teaches agents how to resolve AGENTMUX_BIN, inspect session state, spawn and connect agents, delegate with ask/check, send prompts, read logs, and manage agent lifecycle safely.

TermCanvas is moving from a generic spatial terminal board toward a project-aware agent orchestration canvas. On launch, the app now waits for users to open a folder, creating a new canvas with the + button also asks for the workspace folder first. The near-term roadmap includes `ask --batch` for parallel fan-out delegation, `--report-to` callbacks so delegated agents can notify callers without polling, smarter answer extraction using structured markers instead of prompt-echo search, a read-only canvas snapshot so agents can inspect who else is on the canvas, and improved large-canvas feel with fit-to-content, smoother pan/zoom, and reduced jank with many nodes.

Current macOS builds are unsigned, so macOS may block the app on first launch. After downloading the .dmg or .zip, users move TermCanvas.app to Applications, right-click it in Finder, choose Open, and click Open again when the warning appears. If macOS still blocks it, users open System Settings, navigate to Privacy & Security, scroll to the security section, click Open Anyway for TermCanvas, and open the app again. After the first successful launch, the app opens normally. The app supports exporting and importing full app data as JSON to move setups between installs; development checkouts build with `npm run build` and test with `npm test`.

TermCanvas emerges at a moment when developers increasingly pair with AI coding agents (Claude Code, Codex, OpenCode, Cursor) to manage complex multi-repository workflows. The spatial canvas concept addresses a genuine pain point: traditional terminal tabs become crowded and lack context when juggling multiple repos, services, logs, and agent processes in parallel. By rendering real shell sessions on an infinite, zoomable surface, TermCanvas gives each task a dedicated visual location—akin to how design tools let teams organize artboards—and pairs this with a peer-to-peer agent graph rather than a hierarchical command-and-control dashboard.

The integration of agentmux is central to its vision. Rather than building a heavy agent orchestration UI, TermCanvas stays minimal: it visualizes the real agent topology (spawn and connect edges, with directional arrows) while keeping the terminal itself the primary control surface. Agents spawned on the canvas receive environment variables (AGENTMUX_PROJECT, AGENTMUX_AGENT_NAME, AGENTMUX_BIN) from birth, so any agent framework they host (Claude Code, Codex, etc.) inherits full graph context automatically. This design choice reduces friction—developers do not need to configure agent awareness separately—and lets agents delegate work directly to peers using terminal-native commands like `agentmux ask`.

The app's current direction explicitly targets project-aware workflows: open a project, get a canvas for it, and see terminals, agents, and files in one view without losing context. The roadmap (parallel delegation with `--batch`, callback notifications, structured answer extraction, better large-canvas performance) suggests the maintainer is iterating based on real usage rather than shipping a static product. For developers accustomed to tabbed or split-pane terminals, the spatial metaphor may feel unfamiliar, but for those managing five or more parallel tasks—especially with AI agents involved—the context preservation and visual graph of agent relationships appear designed to reduce cognitive load.

No comments yet. Be the first to share your thoughts!