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.).

Download — grab the latest build from GitHub Releases.

xattr -cr /Applications/TermCanvas.app

Build from source:

git clone https://github.com/blueberrycongee/termcanvas.git
cd termcanvas
npm install
npm run 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.

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.

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

• Live status & completion glow — see at a glance whether an agent is working, waiting, or done
• Event-driven telemetry — Claude Code and Codex stream awaiting_input, tool activity, and turn state via lifecycle hooks, so status transitions land in-frame rather than on a polling delay
• Telemetry truth layer — turn state, tool activity, stall detection, advisory badges, and structured snapshots shared between the UI and Hydra
• Session resume — close and reopen an agent terminal without losing context
• Inline diff cards — review an agent's changes without leaving the canvas

A desktop capybara (opt-in) that tracks your agents via telemetry and reacts: working, waiting, stuck, stall, completed, spa. Uses the same truth layer as the status glow, so its reactions are as accurate as the badges. Walk dust, heart particles, ground shadow, and a handful of idle emotes for a bit of companion texture during long runs.

Session panel renders as a tree: projects → worktrees → agent sessions. Collapse / expand whole projects, jump to a running session's terminal, inspect session metadata, resume by click. Git status badges on worktrees reflect the live file-tree state.

Built-in Git panel in the left sidebar — commit history, diff viewer, and git status at a glance without leaving the canvas.

Shell, lazygit, and tmux terminals live alongside AI agents on the same canvas. Star important terminals and cycle through them with ⌘ J / K. Four size presets, customizable titles, per-agent CLI override. New terminals pick up your sticky preferred size — the first manual resize is learned and used for every subsequent "+ Terminal" click, independent of sidebar state.

Token usage and cost dashboard — total spend, per-project and per-model breakdown. Hourly token heatmap, 24-hour cost sparkline, cache hit/miss stats. Quota monitor for 5-hour and 7-day rate limits. Sign in to sync usage across devices.

6 downloadable monospace fonts · dark/light theme · customizable keyboard shortcuts · minimum contrast ratio for accessibility · English and Chinese (auto-detected) · auto-update with in-app changelog.

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

Usage: termcanvas <project|terminal|telemetry|diff|state> <command> [args]

Project commands:
  project add <path>                          Add a project to the canvas
  project list                                List all projects
  project remove <id>                         Remove a project
  project rescan <id>                         Rescan worktrees for a project

Terminal commands:
  terminal create --worktree <path> --type <type>   Create a terminal
          [--prompt <text>] [--parent-terminal <id>] [--auto-approve]
  terminal list [--worktree <path>]            List terminals
  terminal status <id>                         Get terminal status
  terminal output <id> [--lines N]             Read terminal output (default 50 lines)
  terminal destroy <id>                        Destroy a terminal

Telemetry commands:
  telemetry get --terminal <id>                Get terminal telemetry snapshot
  telemetry get --workflow <id> [--repo <p>]   Get workflow telemetry snapshot
  telemetry events --terminal <id>             List recent terminal telemetry events

Other commands:
  diff <worktree-path> [--summary]             View git diff for a worktree
  state                                        Dump full canvas state as JSON

Flags:
  --json    Output in JSON format

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.

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 .

hydra dispatch --workbench <id> --dispatch review --role reviewer \
  --intent "Independent review of the OAuth change" \
  --depends-on dev --repo .

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

Role files choose the CLI / model / reasoning profile. The caller chooses the role; Hydra resolves the terminal from that role definition.

Usage: hydra <command> [options]

Lead-driven workbench:
  init        Create a workbench context
  dispatch    Dispatch a unit of work into a workbench
  watch       Wait until a decision point is reached
  redispatch  Re-run an eligible/reset dispatch
  approve     Mark a dispatch output as approved
  reset       Reset a dispatch (and downstream by default) for rework
  ask         Ask a completed dispatch a follow-up question via session resume
  merge       Merge completed parallel dispatch branches
  complete    Mark a workbench as completed
  fail        Mark a workbench as failed

Inspection:
  status      Show structured workbench + assignment state
  ledger      Show workbench event log
  list        List direct spawned agents (pass --workbenches for workbenches)
  list-roles  Show available role definitions

Housekeeping:
  spawn      Create one direct isolated worker terminal
  cleanup    Clean up workbench state or direct spawned workers
  init-repo  Sync Hydra instructions into CLAUDE.md and AGENTS.md

# Repo setup
hydra init-repo

# Start a Lead-driven workbench
hydra init --intent "fix the login bug" --repo .

# Dispatch a unit of work and wait for the decision point
hydra dispatch --workbench <id> --dispatch dev --role dev \
  --intent "Fix the login bug and add regression coverage" --repo .
hydra watch --workbench <id> --repo .

# Ask a completed dispatch a follow-up question without re-running it
hydra ask --workbench <id> --dispatch dev \
  --message "Why did you change the session validation path?" --repo .

# Send a dispatch back for rework
hydra reset --workbench <id> --dispatch dev \
  --feedback "The fix regressed the refresh-token path. Rework it." --repo .
hydra redispatch --workbench <id> --dispatch dev --repo .

# Direct isolated worker
hydra spawn --task "investigate the flaky CI failure" --repo .

# Inspection
hydra status --workbench <id> --repo .
hydra ledger --workbench <id> --repo .
hydra list --workbenches --repo .
hydra list-roles --repo .

# Cleanup
hydra cleanup --workbench <id> --repo . --force
hydra cleanup <agent-id> --force

Lead-driven workbenches advance through validated result.json evidence inside .hydra/workbenches/. The telemetry truth layer provides real-time turn_state, last_meaningful_progress_at, derived_status, and session attachment data — used by both the UI and Hydra's watch / retry / health-check paths.

Typical workflow: write a PRD → run hydra init-repo once → let the Lead choose direct work vs spawn vs init/dispatch/watch → monitor via hydra watch or the canvas UI → read report.md before approving / resetting / completing. See Hydra Orchestration Guide for the control-plane details, and the Hydra Panoramic Flowchart for the updated state / file model.

All shortcuts are customizable in Settings → Shortcuts. On Windows/Linux, the default app shortcuts use Alt.

Acknowledgements — lazygit is integrated as a built-in terminal type for visual git management on the canvas.

TermCanvas is evolving from a local desktop tool into a cloud-native AI development platform. Here's what's coming:

Move task execution from your local machine to the cloud. Spin up AI agents on remote runtimes — your tasks run in managed environments with full git, toolchain, and dependency support, while your canvas remains the single pane of glass.

• Hosted agent execution — delegate Claude, Codex, and other agent tasks to cloud workers with on-demand compute
• Persistent remote sessions — close your laptop, come back later, your agents are still working
• Parallel cloud workers — scale out Hydra workflows across multiple cloud instances instead of local terminals

End-to-end automation from idea to shipped code, powered by cloud runtime:

• Intent → Plan → Implement → Review → Merge — a fully automated pipeline where you describe what you want and the system handles the rest
• Continuous vibe loop — agents plan, implement, self-review, and iterate autonomously until the result meets acceptance criteria
• Pipeline-as-code — define reusable workflow templates for common tasks (bug triage, feature implementation, migration, refactoring)
• Human-in-the-loop checkpoints — configurable approval gates at any stage for when you want to stay in control

The goal is simple: you describe intent, TermCanvas handles the rest. Your canvas becomes a mission control for autonomous AI development — monitor progress, review results, intervene when needed, and let the cloud do the heavy lifting.

Contributing — fork, branch, and open a PR. Licensed under MIT.