canopy

A lightweight menu-bar git-worktree + dev-service manager.
Every branch checked out, provisioned, and running — side by side.

_{Linux & Windows builds are experimental — feedback welcome. See Install for the one-line quarantine fix on macOS.}

Canopy discovers every worktree of your registered repos, provisions each one (dependencies, an isolated database, deterministic ports), and lets you start/stop services, watch logs, manage databases, and change ports — from a tray popover and a main window. Built for fast multi-repo / submodule workflows like ToolJet.

• Platform: macOS arm64 (Apple Silicon). Linux & Windows ports are experimental — they compile and pass CI, but aren't yet validated on a desktop.
• Stack: Tauri 2 (Rust) + React + zustand
• Current version: 0.4.7

Working on several branches at once with git worktree means each checkout needs its own dependencies, its own database, and its own set of ports — otherwise they collide. Doing that by hand is tedious and error-prone. Canopy automates it:

• Isolated per worktree — each worktree gets its own database (<repo>_<slug>) and a deterministic set of ports (basePort + index*10), so multiple branches run side by side.
• Zero-bash provisioning — how a worktree is set up (env vars, install/build/migrate/teardown) is declared once in the repo via .worktreemanager.json, so it travels with the branch.
• One place to run everything — start/stop services, tail logs, pull, snapshot/restore/switch databases, edit ports — from a tray popover or the main window.

• macOS on Apple Silicon (arm64)
• A version manager providing the Node version your project needs (e.g. Node 22.15.1 for ToolJet)
• Postgres running locally (for database-backed projects like ToolJet)
• git
• A .worktreemanager.json in the repo (commit it so it travels per branch) — see the Configuration guide

Homebrew (recommended — handles quarantine for you):

brew install --cask emidhun/canopy/canopy

Or the DMG from Releases: Canopy isn't notarized yet, so macOS quarantines it on download — clearing that quarantine is the step that matters:

hdiutil attach ~/Downloads/Canopy_<version>_aarch64.dmg
cp -R "/Volumes/Canopy/Canopy.app" /Applications/
hdiutil detach "/Volumes/Canopy"
xattr -dr com.apple.quarantine /Applications/Canopy.app      # clears quarantine
open /Applications/Canopy.app

Or drag Canopy to Applications and run only the xattr -dr com.apple.quarantine line. On macOS Sequoia you can instead use System Settings → Privacy & Security → Open Anyway.

.AppImage, .deb, and .rpm packages are on the Releases page. They build and pass CI but haven't been validated on a real desktop yet — issues welcome.

An NSIS installer (Canopy_<version>_x64-setup.exe) is published on the Releases page. Download it, run it, and launch Canopy from the Start menu — it lives in the system tray. Windows SmartScreen may warn on first run because the installer isn't code-signed yet; choose More info → Run anyway. Like Linux, the Windows port compiles and is published for early adopters but hasn't been validated on a real desktop — feedback welcome. Step-by-step notes are in the Windows install guide.

Canopy runs as a menu-bar / tray app — look for the fork icon after launch. Full install/signing details are in docs/distribution.md.

1. Click the Canopy icon in the menu bar → Open Manager.
2. Settings (gear, top-right) → Add repo → pick your repo's main checkout folder. Set the worktree directory and define your services (id / name / command / cwd / basePort).
3. Commit a .worktreemanager.json in the repo describing env overrides + setup commands (see the Configuration guide; a ToolJet example is in docs/tooljet-config.md).
4. New worktree → pick a new or existing branch/tag → Canopy creates the worktree, provisions it, and streams progress.
5. Start all to boot the worktree's services, then click a service's port (:3000) to open it in the browser.

The full walkthrough — with databases, ports, pull, and troubleshooting — is in the User Guide.

# one-time
npm install

# standard preamble for build commands on this machine (Node 22 + cargo on PATH)
export PATH="$HOME/.asdf/installs/nodejs/v22.15.1/bin:$PATH" && source "$HOME/.cargo/env"

npm run tauri dev      # run the full app (both windows + tray), hot-reloads
npm run build          # type-check + build the frontend
npm run tauri build    # release .app bundle

From src-tauri/: cargo check (fast Rust check) and cargo test --lib (unit tests).

See docs/development.md for prerequisites, the release/DMG steps, and the environment gotchas that have bitten us (Node 18 vs 22, pg_dump versioning, the DMG-build hang).

The full documentation is a static site in website/ — 31 pages covering install, onboarding, every feature, both settings scopes, the config-file reference, worked examples, and building from source, with screenshots of every screen in light and dark.

node website/scripts/build.mjs   # content/*.md → website/site/
node website/scripts/serve.mjs   # preview on http://localhost:4180

It has no dependencies: the content is Markdown and the generator is plain Node. Pushing a change under website/ publishes it through .github/workflows/docs.yml. See website/README.md for how to write a page, add a screenshot, or change the look.

• Settings & state live in ~/Library/Application Support/com.midhunkumare.canopy/ (settings.json, state.json).
• See CONTRIBUTING.md for dev setup and commit conventions.

Canopy is open source under the GNU AGPL-3.0. Using the app imposes no obligations on you; the copyleft applies if you modify and distribute (or host) Canopy itself. Optional commercial team/cloud add-ons may be offered separately in the future.