canopy

canopy is a terminal UI for developers running multiple AI coding agents in parallel. One view. All your agents.

• Why canopy?
• Demo
• Requirements
• Install
• Usage
• Keybinds
• How it works
• Config
• Editor Integration
• Contributing
• License

Each worktree gets a dedicated tmux session so your agent runs in a real terminal with full PTY support. Canopy sits above all of them: monitor every agent at a glance and drop in when you need to.

Managing 3–5 parallel AI agents across separate terminals is chaotic. You have no overview of what's running, you're constantly switching windows, and there's no signal for when an agent needs your input. Canopy gives you one persistent view: see every agent's state, catch anything waiting for you, and drop in when needed.

• tmux (any modern version)
• An AI coding agent on your PATH (e.g. Claude Code, Codex, Aider)
• A git repository

Quick install (Linux & macOS):

curl -fsSL https://raw.githubusercontent.com/isacssw/canopy/main/install.sh | sh

Homebrew:

brew install isacssw/tap/canopy

With Go:

go install github.com/isacssw/canopy/cmd/canopy@latest

Run from anywhere inside your git repo:

canopy

First run will open a short setup wizard to configure your agent command and give it a name.

canopy --help      # show keybinds and usage
canopy --version   # print version

Config is saved to ~/.config/canopy/config.json.

Click any worktree in the left panel to select it. Use the scroll wheel to scroll the output panel.

Press a to drop into the agent's tmux session and interact with it directly. Canopy suspends while you're attached. Press Ctrl+b d to detach and return to canopy.

Nested tmux sessions: If you're already running inside a tmux session, canopy opens a nested session. To detach from the inner (canopy) session, press Ctrl+b twice then d. The first Ctrl+b is consumed by your outer session, so you need a second one to reach the inner session. To avoid the double-prefix, set "tmux_prefix": "C-Space" (or any other key) in your config — canopy's sessions will use that prefix instead.

When an agent transitions to waiting, canopy marks it with a yellow ● badge in the list and emits a terminal bell, so you notice even when working in another window. The badge clears when you navigate to that worktree.

The status bar shows a live summary of agent counts (e.g. 1 running · 2 waiting) on the right side.

With idle_timeout_secs set, any agent that has produced no new output for that many seconds is automatically promoted from running to waiting. This is a useful fallback for agents that don't emit standard input-prompt patterns. Set to 0 (the default) to disable.

When you press r, canopy creates a detached tmux session named canopy_<repo-hash>_<branch> and launches your agent command inside it. The output panel shows a live snapshot of the tmux pane, refreshed every 500ms.

Session names include a short hash of the repo root, so branches with the same name across different repos never collide.

Agents keep running after you quit canopy. They're just tmux sessions. You can reattach at any time with tmux attach -t <session-name> or by reopening canopy and pressing a.

~/.config/canopy/config.json:

{
  "agents": [
    { "name": "claude", "command": "claude" },
    { "name": "claude-yolo", "command": "claude --dangerously-skip-permissions" },
    { "name": "codex", "command": "codex" }
  ],
  "left_panel_width": 38,
  "theme": "github-dark",
  "output_colors": "adaptive",
  "idle_timeout_secs": 0,
  "tmux_prefix": "C-Space"
}

With a single agent configured, pressing r starts it immediately. With two or more, a picker appears so you can choose which profile to run.

Pressing D on a worktree asks for confirmation. After pressing y, canopy starts a 5-second countdown displayed in the status bar (Deleting "branch" in 5s… [u]ndo). Press u, esc, or n at any point during the countdown to cancel. The delete only executes when the timer reaches zero.

For Neovim users, see canopy.nvim for setup instructions and integration.

Set EDITOR=code or EDITOR=cursor and press e from diff view. Canopy opens the selected file at the first changed hunk line in your GUI editor.

See CONTRIBUTING.md. Contributions, bug reports, and feature requests are welcome.

MIT, see LICENSE