TermCanvas

Your terminals, on an infinite canvas.

termcanvas.dev →

TermCanvas spreads all your terminals across an infinite spatial canvas — no more tabs, no more split panes. Drag them around, zoom in to focus, zoom out to see the big picture.

It organizes everything in a Project → Worktree → Terminal hierarchy that mirrors how you actually use git. Add a project, and TermCanvas auto-detects its worktrees. Create a new worktree from the terminal, and it appears on the canvas instantly.

New to TermCanvas? Read the full User Guide — every interaction explained, every keyboard shortcut, plus the non-obvious tricks (⌘E focus chain, drag-to-stash, session replay, etc.).

Quick Start

Download — grab the latest build from GitHub Releases.

[!IMPORTANT] Apple Silicon (M-series) Macs — pick the file with arm64 in its name Files with arm64 in the filename (e.g. TermCanvas-X.Y.Z-arm64.dmg, TermCanvas-X.Y.Z-arm64-mac.zip) are native Apple Silicon builds. Files without arm64 are Intel (x64) builds — they'll still launch on M-series Macs via Rosetta 2, but you'll see noticeable lag when panning/zooming the canvas.

To verify after install: open Activity Monitor, find TermCanvas, and check the Kind column — it should say Apple, not Intel. If it says Intel, delete the app and redownload the arm64 variant.

[!WARNING] macOS note for unsigned builds If macOS says TermCanvas is damaged or blocks launch because the app is unsigned, clear the quarantine attribute and try again:

xattr -cr /Applications/TermCanvas.app

If you installed the app somewhere else, replace the path with the actual app location.

Build from source:

This workspace uses pnpm, and pnpm-lock.yaml is the canonical lockfile.

git clone https://github.com/blueberrycongee/termcanvas.git
cd termcanvas
pnpm install
pnpm dev

Install CLI tools — after launching the app, go to Settings → General → Command line interface and click Register. This adds termcanvas and hydra to your PATH.

Registration also installs TermCanvas skills and lifecycle hooks for Claude/Codex. For Codex 0.129.0 and newer, TermCanvas writes the required hook trust state in ~/.codex/config.toml so the generated hooks are reviewed/trusted and continue to emit terminal lifecycle and telemetry events.

Features

Canvas

Infinite canvas — pan, zoom, and arrange terminals freely. Three-layer hierarchy: projects contain worktrees, worktrees contain terminals. New worktrees appear automatically as you create them.

Double-click a terminal title bar to zoom-to-fit. Drag to reorder. Box-select multiple terminals. Draw and annotate freely on the canvas itself with the Free Canvas tool — sketches, callouts, and grouping lines live alongside your terminals. Save your entire layout to a .termcanvas file.

AI Coding Agents

First-class support for Claude Code, Codex, Kimi, Gemini, and OpenCode.

• Glance at any tile to know what it's doing — a coloured status dot tells you whether the agent is thinking, awaiting input, idle, or done
• Pick up where you left off — close and reopen an agent terminal without losing the conversation
• Review changes in place — inline diff cards let you read an agent's edits without leaving the canvas

Sessions Panel

Every past Claude / Codex conversation in your projects, organised as projects → worktrees → sessions. Click any row to replay it, or jump straight to the running terminal. Worktrees show their live git status so you can tell at a glance what's clean.

Git

Commit history, diff viewer, and live git status — built into the sidebar so you never need to leave the canvas to check what changed.

Terminals

Shell, lazygit, and tmux terminals live alongside AI agents on the same canvas. Star the ones you keep coming back to (⌘F) and cycle through just those with ⌘] / ⌘[ — use ⌘G to choose whether you're cycling all terminals, just starred, or whole worktrees. Custom titles, per-agent CLI override, and your preferred terminal size is remembered after the first manual resize.

Usage Tracking

Track how much you're spending on Claude and Codex — across all projects, broken down by model, with quota meters for the 5-hour and 7-day rate limits. Sign in to keep usage in sync across devices.

Settings

Downloadable monospace fonts · dark / light theme · rebindable keyboard shortcuts · adjustable contrast for accessibility · English and Chinese · in-app auto-update.

CLI

Both CLIs are bundled with the app. Register them from Settings to use in any terminal.

termcanvas

Usage: termcanvas <group> <command> [args]

Groups:
  project        add | list | remove | rescan
  worktree       list | create | remove
  terminal       create | list | status | output | destroy | set-title
  workflow       Lead-driven Hydra workflow over HTTP (init / dispatch / watch …)
  telemetry      get | events
  pin            add | list | show | update | rm
  diff           <worktree-path> [--summary]
  state          dump full canvas state as JSON

Common shapes:
  project add <path>
  worktree create --repo <path> --branch <name> [--from <ref>]
  terminal create --worktree <path> --type <claude|codex|shell|…>
          [--prompt <text>] [--parent-terminal <id>] [--auto-approve]
  terminal output <id> [--lines N]              # default 50
  telemetry get --terminal <id>
  telemetry get --workflow <id> --repo <path>
  pin add --title <t> [--body <b>] [--link <url>] [--link-type <type>]

Flags:
  --json    Machine-readable output for any command

termcanvas project add ~/my-repo
termcanvas terminal create --worktree ~/my-repo --type claude --prompt "Audit the auth flow and fix the root cause"
termcanvas terminal status <id>
termcanvas telemetry get --terminal <id>
termcanvas diff ~/my-repo --summary

For Claude/Codex task automation, start a fresh terminal with termcanvas terminal create --prompt "...". termcanvas terminal input is not a supported dispatch path.

hydra

Hydra is TermCanvas's terminal orchestration toolkit for Lead-driven workflows and isolated direct workers. It coordinates git worktrees, assignment/run file contracts, and the telemetry truth layer without taking control away from the agent sessions themselves.

Hydra is now Lead-driven. One main terminal owns the workbench, reads the codebase, and decides what to do at each decision point. Worker terminals stay autonomous. Workbench state lives under repo-local .hydra/workbenches/, and the authoritative contract is on disk: inputs/intent.md, dispatches/<dispatchId>/intent.md, report.md, result.json, and ledger.jsonl. Terminal prose is advisory only; validated result.json is the machine gate.

Role-driven workflows currently target Claude/Codex through the Hydra role registry. If you only need one isolated worker without a Lead-driven DAG, use hydra spawn instead.

This design is inspired by Anthropic's harness design research on long-running agent orchestration, adapted for terminal-based agents where each process is naturally isolated. For the theoretical foundations behind this approach, see Harness Design from a Distribution Perspective.

Getting started

Run hydra init-repo in your project (or click Enable Hydra in the worktree header) to sync the Hydra instructions into CLAUDE.md / AGENTS.md. Then either talk to your main agent, or drive the workflow yourself:

Write a PRD or describe your requirements clearly, then tell the agent:

"Read the Hydra skill. I want you to choose the right mode and autonomously complete this task based on the PRD in docs/prd/auth-redesign.md."

The main agent should classify the task and pick the lightest fitting path:

• Stay in current agent — simple or local tasks, no orchestration overhead
• hydra spawn — a direct isolated worker when the task is clear and self-contained
• hydra init + dispatch + watch — Lead-driven workflow for ambiguous, risky, parallel, or multi-step work

hydra init-repo

hydra init --intent "Add OAuth login" --repo .

hydra dispatch --workbench <id> --dispatch dev --role dev \
  --intent "Implement OAuth login and the tests that cover it" --repo .

hydra watch --workbench <id> --repo .

hyd