Canopy

Product Introduction

1. Definition: Canopy is a native macOS application (built with Swift and SwiftUI) designed as a specialized session manager for Claude Code. It functions as a graphical interface to orchestrate multiple, parallel Claude Code AI agent sessions, each operating within its own isolated git worktree within a single application window.
2. Core Value Proposition: Canopy exists to eliminate the context-switching overhead and manual git "papercuts" associated with using Claude Code for serious, multi-threaded development work. Its primary value is enabling developers to run and manage parallel coding tasks simultaneously—each with its own git branch and dedicated Claude instance—through a unified, efficient interface, thereby reclaiming lost productivity and mental context.

Main Features

1. Parallel Session Management with Git Worktrees: Canopy creates and manages isolated git worktrees for each new session, allowing multiple branches of a single repository to be checked out and worked on simultaneously. It integrates directly with Claude Code's session resumption mechanism (--resume), automatically mapping each worktree tab to its corresponding Claude session ID from ~/.claude/projects/. This ensures all conversational context is preserved across application restarts. The UI presents these sessions as tabs, reordering and sorting via keyboard shortcuts.
2. Token Usage Activity Dashboard: Canopy parses the JSONL session logs written by Claude Code to provide a comprehensive dashboard of token consumption. It visualizes all-time and rolling 12-week input/output token totals, session counts, busiest usage days, model breakdowns (Opus, Sonnet, Haiku), and an hourly heatmap of activity. This feature is built directly into the app, offering native, first-party insight into API usage costs and patterns without requiring external scraping tools.
3. Integrated Workflow Command Palette & Shell: A fuzzy-search command palette (Cmd+K) provides instant access to all sessions, projects, and actions. For parallel workflow execution, a toggleable split-pane terminal (Cmd+Shift+D) launches a full interactive shell scoped to the same worktree as the active Claude session. This allows developers to run auxiliary commands (e.g., git log, npm test) without interrupting the Claude agent or switching windows.
4. Sandboxed Execution Environments: Canopy supports launching Claude Code sessions within secure, isolated virtual machines (VMs). It offers two backends: a Docker Sandbox microVM via sbx (disabling session resume) and a lightweight Apple container runtime (preserving session state by mounting specific paths). This provides configurable security boundaries, preventing the autonomous agent from accessing unintended host filesystem areas like SSH keys or other repositories.
5. One-Click "Merge & Finish" Automation: This feature automates the multi-step git cleanup process after a feature branch is merged. It replaces the manual sequence of checkout, pull, merge, worktree removal, and branch deletion with a two-phase confirmation dialog. The first phase shows the merge target and conflict status; the second phase lets the user select which components to clean up (worktree directory, feature branch, or both).

Problems Solved

1. Pain Point: The "tab graveyard" and context-switching tax. Developers using Claude Code for complex projects face constant interruption from managing git state (stashing, checking out), juggling multiple terminal windows, losing conversational context, and performing repetitive manual cleanup tasks like worktree and branch removal after merging.
2. Target Audience: The primary users are software engineers, full-stack developers, and open-source maintainers who utilize Claude Code for substantial, production-level coding tasks. This includes individual developers working on feature branches, teams managing parallel development streams, and any user who needs to context-switch between coding tasks without losing state or progress.
3. Use Cases: Canopy is essential for scenarios like: working on a bug fix while simultaneously developing a new feature; conducting a code review in one session while tests run in another; investigating a flaky test without halting ongoing development; and managing projects with frequent parallel work that requires clean branch isolation and streamlined merges.

Unique Advantages

1. Differentiation: Unlike a standard terminal emulator or a generic IDE with Claude plugins, Canopy is a dedicated, purpose-built tool that tightly integrates Claude Code's session management with git's worktree functionality. It replaces the fragile, manual workflow of managing multiple terminal tabs and git commands with a single, unified interface that understands the relationship between sessions, branches, and conversation history. Its native macOS SwiftUI implementation (no Electron) ensures performance, low resource usage, and a fluid user experience.
2. Key Innovation: The core innovation is the deep, bidirectional integration between a native macOS GUI, git worktrees, and Claude Code's session state. By automatically handling worktree creation, session resumption, configuration file copying, and terminal scoping, Canopy transforms git worktrees from a manual developer tool into an automated, session-aware backend for parallel AI-assisted development. The token Activity Dashboard is another key innovation, providing unique, native observability into Claude API usage.

Frequently Asked Questions (FAQ)

1. How does Canopy resume my Claude conversations after closing and reopening the app? Canopy scans the ~/.claude/projects/ directory for JSONL session logs, identifies the most recent session associated with each worktree's path, and passes that session ID to the claude --resume command when relaunching a tab. This preserves the full conversation history and context automatically.

2. What are the sandbox options in Canopy, and which one should I use? Canopy offers two sandbox backends for security: a Docker-based microVM (sbx) and a native Apple container. The Docker sandbox (sbx run) is highly isolated but does not allow session resume. The Apple container sandbox (macOS 26+, Apple silicon) mounts your project and ~/.claude state, allowing session resume while still isolating the rest of your host system. The choice depends on your security requirements and need for session persistence.

3. Can Canopy be used without Claude Code installed, or is it just a frontend for it? Canopy requires Claude Code (claude binary in your $PATH) to function. It is not a standalone AI tool but a sophisticated session manager and workflow orchestrator built specifically to enhance the experience of using Claude Code for parallel, multi-branch development.

4. How does the "Merge & Finish" feature prevent accidentally deleting unmerged work? The feature uses a two-step confirmation process. First, it displays the proposed merge target, shows any conflicting files, and displays the commit count. The user must confirm this information before proceeding. Only then does it offer options to clean up the worktree directory and/or the feature branch, ensuring an explicit decision is made at each stage.

5. Does Canopy work with IDEs like VS Code or Cursor? Yes. While Canopy handles the parallel session and git worktree management, it includes integration for opening the worktree's directory in your preferred IDE. The project's context menu provides an "Open in IDE" option, and the command palette can target specific IDEs, streamlining the transition from the terminal-based session to a graphical code editor.