Supacode
on macOS

01 What is Supacode?

Supacode is a native macOS application that serves as a command center for AI coding agents. Rather than wrapping web technologies like Electron, it is written entirely in Swift using libGhostty (the GPU-accelerated terminal core from the Ghostty terminal emulator) for rendering and The Composable Architecture (TCA) for state management.

Its core idea is simple: modern AI-assisted development involves running multiple agents simultaneously on different tasks. Supacode solves the "1000 tabs" problem by giving each agent its own isolated git worktree, its own persistent terminal state, and a unified sidebar to manage them all.

02 Requirements

Supacode has a strict macOS version floor due to its use of modern SwiftUI APIs and GhosttyKit.

Checking prerequisites

$ sw_vers                      # check macOS version
$ git --version                 # verify git is installed
$ gh auth status                # verify gh is installed and authenticated
$ claude --version              # if using Claude Code
$ codex --version               # if using Codex

03 Installation

Option A — Homebrew (recommended)

The fastest way to get Supacode running:

$ brew install supacode

Then launch from Spotlight (⌘Space → "Supacode"), Launchpad, or from the terminal:

$ open -a Supacode

Option B — Download from supacode.sh

Visit supacode.sh to download the latest .dmg. Drag Supacode to your /Applications folder and launch it. macOS Gatekeeper may prompt you the first time — open System Settings → Privacy & Security and click Open Anyway.

Option C — Build from source

For contributors and those who want to run the latest unreleased changes:

$ git clone https://github.com/supabitapp/supacode.git
$ cd supacode
$ mise install                  # install pinned Zig, swiftlint, etc.
$ make doctor                   # diagnose prerequisites, prints fixes
$ make build-ghostty-xcframework # compile GhosttyKit from Zig source
$ make build-app                # build the macOS app (Debug)
$ make run-app                  # build and launch

Development / quality commands

$ make check    # run swiftformat + swiftlint
$ make test     # run the test suite
$ make format   # run swift-format

Checking for updates

Inside Supacode: press ⌘ U or navigate to the menu. Supacode offers both a stable channel and a tip (latest commits) build channel. Switch between them in Settings.

04 First-Run Setup

1. Launch Supacode. The sidebar will be empty — no repositories yet.

2. Add a repository. Click the + button in the sidebar, or press ⌘ ⇧ O. Browse to any local git repository you want to work in. Supacode will discover all its existing worktrees automatically.

3. Choose your default editor. Supacode can open worktrees in VS Code, Cursor, Xcode, or any editor installed via its bundle ID. Set this in Settings → General. Once set, ⌘ O opens the selected worktree in that editor instantly.

4. Authenticate GitHub CLI if you want PR and CI features: run gh auth login in your terminal, then enable GitHub integration in Supacode's Settings.

5. Configure a repository setup script (optional but recommended). In Repository Settings → Repository Commands, add the command that boots your agent — e.g. claude --dangerously-skip-permissions or codex. This will auto-run whenever you create a new worktree.

6. Create your first worktree with ⌘ N. Supacode creates the git worktree, opens a terminal in it, and optionally runs your setup script.

05 The Mental Model

Understanding the three-layer hierarchy makes Supacode intuitive:

06 Working with Repositories

Adding a repository

Press ⌘ ⇧ O or click the + in the sidebar. Supacode accepts both regular repositories and bare repositories. When you add a repo, it scans for and imports all existing git worktrees automatically.

Repository settings

Each repository has its own settings panel (accessible from the sidebar's context menu or via Settings). Key per-repository options:

Where worktrees live on disk

07 Working with Worktrees

Creating a worktree

Press ⌘ N from anywhere in Supacode. Depending on your repository settings:

• Prompted mode: Supacode asks for a branch name and base ref. Use this for named, intentional work.
• Auto mode: Supacode generates a branch name immediately (fast creation for quick agent tasks). You can rename it afterward.

What happens when a worktree is created

1. Supacode creates a real git worktree under ~/.supacode/repos/<repo>/ on a new branch.

2. The worktree appears in the sidebar under its repository, selected automatically.

3. A dedicated terminal opens for the worktree, starting in its directory.

4. If a setup script is configured, Supacode runs it immediately in the first terminal tab.

Managing worktrees

Renaming branches

Auto-generated branch names can be random or generic. Click the branch name in the toolbar to rename it without leaving the app. You can also teach your agent to rename branches automatically (see the Tips section).

08 The Built-in Terminal

Supacode embeds a full terminal powered by GhosttyKit in the detail pane. Unlike a web-based terminal, this is GPU-accelerated and handles heavy agent output without stuttering.

Tabs and splits

Each worktree's terminal is fully multi-tab and multi-pane. The recommended tab layout when running agents:

Within a tab, splits let you keep related commands side by side. Splits support drag-and-drop reorganization and can be resized, equalized, or zoomed via Ghostty split actions.

Per-worktree terminal state

When you switch worktrees in the sidebar, Supacode restores that worktree's complete terminal state: tabs, splits, scroll position, notifications, and focused surface. Switching between worktrees is instant — it's purely a UI switch with no process teardown.

Persistent sessions (ZMX)

Supacode bundles a ZMX multiplexer. Sessions persist through app restarts and updates — if you quit Supacode, any running agents keep running in the background. When you relaunch, all your tabs reattach exactly where you left them.

Tab context menu

• Close Tab
• Close Other Tabs
• Close Tabs to the Right
• Close All Tabs

Terminal search

09 Supported Coding Agents

Supacode uses a BYOA (Bring Your Own Agent) model. Any agent that runs in a terminal shell works. The four officially supported harnesses get native integration features (agent-aware notifications, the Supacode CLI, and the bundled skill file):

Harness integration features

For the four natively-supported harnesses, Supacode provides three extra integration hooks:

• Notifications: macOS toast notifications + in-app alerts when an agent needs attention or finishes a task.
• Supacode CLI: A bundled CLI the agent can invoke to drive the GUI — e.g. "open this directory as a new Supacode project" or "create a worktree for this branch".
• Skill file: A bundled skill definition so the agent understands how to manage Supacode itself (creating worktrees, renaming branches, etc.).

10 Auto-Starting Agents

The most powerful workflow pattern in Supacode is configuring a repository setup script that automatically boots your agent in every new worktree. This means pressing ⌘ N and having an agent ready to work within seconds — no manual startup required.

Setting up a setup script

In Supacode: open a repository → click its settings icon → Repository Commands → Setup Script. Enter your agent command.

Example setup scripts

# Auto-start Claude Code (skipping permission prompts)
claude --dangerously-skip-permissions

# Auto-start Codex
codex

# Install dependencies first, then start agent
pnpm install && pnpm prisma generate && claude

# Start the dev server in the background, then start agent
pnpm dev & claude

# Multiple steps with a custom script
./scripts/setup-dev.sh && codex

supacode.json — per-project agent instructions

Place a supacode.json at the root of your repository to store Supacode configuration in version control, shareable with your team:

{
  "runScript": "pnpm dev",
  "setupScript": "pnpm install && claude --dangerously-skip-permissions",
  "archiveScript": "docker compose down"
}

Teaching agents about Supacode via AGENTS.md

Add instructions to your repository's AGENTS.md (or CLAUDE.md, .cursorrules) so agents understand how to use Supacode's own CLI and manage worktrees:

# Example AGENTS.md additions

Before starting your task, check the current git branch name.
If it's something generic (like a random animal name), rename it
to something descriptive. Do not rename the main branch.

Use the Supacode CLI to create new worktrees for large sub-tasks
rather than doing everything in one worktree.

When finished, run: git add -A && git commit -m "feat: ..."
then push your branch and the PR will appear in Supacode's sidebar.

11 Parallel Agent Workflows

Supacode's core value proposition is running many agents simultaneously. Here's how to structure parallel work effectively:

The isolation guarantee

Each worktree is a completely independent git checkout on its own branch. Agent A working in feature-auth can never touch files in feature-payments — they are separate directories. Git tracks changes independently. There is no locking, no conflicts between concurrent agents.

A practical parallel workflow

# Worktree 1: Agent handles the API layer
⌘N → branch: feat/api-v2-endpoints
→ Agent: "Implement the new /users/v2 endpoints from spec.md"

# Worktree 2: Agent writes tests
⌘N → branch: feat/api-v2-tests
→ Agent: "Write comprehensive tests for the v2 API surface"

# Worktree 3: Agent updates documentation
⌘N → branch: docs/api-v2-reference
→ Agent: "Update the API reference docs to reflect the v2 changes"

# You review all three in parallel in the sidebar
# Merge the ones that look good, archive the rest

Navigating between parallel agents

12 Keyboard Shortcuts

Supacode defines a lean set of app-level shortcuts. Terminal shortcuts come from your Ghostty configuration.

Application shortcuts

Terminal search shortcuts

13 Command Palette

Press ⌘ P to open the Command Palette — a fuzzy-search interface that gives you keyboard access to every action and worktree in Supacode. It's the fastest way to switch context or trigger any action without reaching for the mouse.

What the Command Palette surfaces

• Jump directly to any worktree across all repositories
• Run any repository command (run script, setup script)
• Open a worktree in your editor
• Access repository settings
• Create a new worktree
• Archive or delete a worktree
• GitHub PR actions for the current worktree

14 Repository Commands

Repository Commands is where you define the three repeatable command slots that Supacode reuses across a project's lifetime:

# Good examples:
pnpm dev
pnpm test --watch
bin/rails server
cargo test
./gradlew run

# Good examples:
docker compose down
pkill -f "rails server"
kill $(cat .server.pid)

Setup Script on create

Runs once after a new worktree is created. This is the key integration point for agents — put your agent launch command here and every new worktree will boot straight into an agent session.

# Start Claude Code immediately
claude --dangerously-skip-permissions

# Install deps then start Codex
pnpm install && codex

# Generate local artifacts before agent starts
pnpm prisma generate && pnpm run seed:dev && claude

Where these settings are stored

If your repository contains supacode.json at its root, Supacode reads and writes values there — allowing the team to share the configuration via version control. Otherwise, values are stored in ~/.supacode/settings.json under the repositories map.

15 GitHub CLI Integration

Supacode connects to GitHub via the official GitHub CLI (gh). Once enabled, it adds a layer of GitHub awareness to every worktree — PR status, CI results, and merge actions all appear in the sidebar and toolbar.

Setup

# 1. Install the GitHub CLI if you haven't already
$ brew install gh

# 2. Authenticate
$ gh auth login

# 3. Verify authentication
$ gh auth status

# 4. Enable in Supacode Settings → GitHub → GitHub CLI Integration

What GitHub integration provides

16 PR & CI Workflows

With GitHub integration enabled, Supacode attaches pull request data to any worktree whose branch maps to an open PR. The result is a full PR review experience without opening a browser.

PR actions available in Supacode

• Open the PR on GitHub (⌃ ⌘ G)
• Mark a draft PR ready for review
• Merge the PR (using the configured merge strategy)
• Close the PR
• Open failing check details
• Copy the failing job URL
• Copy failing CI logs to clipboard
• Re-run failed CI jobs

Merge strategies

Set your preferred merge strategy per repository in Repository Settings:

• Merge — creates a merge commit
• Squash — squashes all commits into one
• Rebase — rebases commits onto the base branch

Auto-archive after merge

Enable Automatically archive merged worktrees in Repository Settings. When a PR is merged, Supacode runs the archive script (if configured) and moves the worktree out of the active list automatically — keeping your sidebar clean without manual housekeeping.

A complete agent-to-PR workflow

17 Notifications

Running many agents in parallel creates an attention management problem — how do you know which worktree needs your review without constantly checking every terminal? Supacode's notification system solves this.

How notifications work

Notifications are generated from terminal activity and attached to the specific worktree surface that produced them. For supported harnesses (Claude Code, Codex, Pi), the agent itself can signal when it's finished or needs input.

Where notifications appear

• Sidebar: An unread indicator on the worktree row so you see at a glance which sessions need attention
• Toolbar: An aggregated notifications popover showing all pending notifications across all worktrees
• macOS system notifications: Toast notifications so you can be notified even when Supacode is not the focused window

Notification navigation

Selecting a notification in the popover jumps you back to the exact terminal surface (tab and pane) that produced it — not just the worktree, but the precise split.

18 Settings & Storage

Where Supacode stores data

Global settings (settings.json)

supacode.json (per-repository)

Place this file at the root of your repository to store per-project configuration in version control, making it shareable with your team:

{
  "runScript":     "pnpm dev",
  "setupScript":   "pnpm install && claude --dangerously-skip-permissions",
  "archiveScript": "docker compose down"
}

When supacode.json exists in a repository, Supacode reads and writes settings there instead of to ~/.supacode/settings.json.

19 Terminal Theming

Supacode's UI chrome (sidebar, toolbar, backgrounds) respects macOS appearance — Light, Dark, or System. The terminal itself is themed via your Ghostty configuration file.

Ghostty config location

~/.config/ghostty/config

Key terminal appearance settings

# ~/.config/ghostty/config — affects Supacode's terminal

# Font
font-family = "JetBrains Mono"
font-size = 14

# Color scheme (pick a built-in or define custom)
theme = "Catppuccin Mocha"
# or: theme = "Dracula"
# or: theme = "Tokyo Night"
# or: theme = "Gruvbox Dark"

# Light/dark adaptive theme
theme = light:rose-pine-dawn,dark:catppuccin-mocha

# Transparency (0 = opaque, 1 = fully transparent)
background-opacity = 0.92

# Padding inside the terminal
window-padding-x = 12
window-padding-y = 8

# Cursor style: block, bar, underline
cursor-style = bar

# Bold text rendering
bold-is-bright = true

Custom color palettes

# Define a fully custom color scheme in Ghostty config
palette = 0=#1e1e2e   # black (background)
palette = 1=#f38ba8   # red
palette = 2=#a6e3a1   # green
palette = 3=#f9e2af   # yellow
palette = 4=#89b4fa   # blue
palette = 5=#cba6f7   # magenta
palette = 6=#89dceb   # cyan
palette = 7=#cdd6f4   # white
background = 1e1e2e
foreground = cdd6f4

20 supacode.json Reference

A supacode.json file at the root of your repository is the cleanest way to configure Supacode per-project and share settings with your team via version control.

// supacode.json — place at repository root
{
  // The command run when pressing ⌘R
  "runScript": "pnpm dev",

  // Runs once in a new worktree's terminal after creation
  "setupScript": "pnpm install && claude --dangerously-skip-permissions",

  // Runs before a worktree is archived
  "archiveScript": "docker compose down"
}

Integration with CLAUDE.md / AGENTS.md

Pair supacode.json with an instructions file for your agent. The Supacode documentation recommends a section in AGENTS.md (or CLAUDE.md for Claude Code) that teaches the agent how to use Supacode:

# AGENTS.md — agent instructions for this repo

## Supacode Conventions

- Check the current branch name before starting. If it's generic
  (animal name, random string), rename it to reflect the task.
  Do NOT rename `main`.

- When creating a PR, use a clear conventional commit title.
  Format: `feat: <description>` or `fix: <description>`

- After completing changes: `git add -A && git commit -m "<msg>"`
  then `git push -u origin HEAD`

- If the task is too large, split it into sub-tasks. Use the
  Supacode CLI to create additional worktrees for parallel work.

21 Tips & Best Practices

Name your worktrees meaningfully

Auto-generated branch names are fast but hard to navigate when 10 worktrees are active. Use one of these approaches:

• Enable prompted worktree creation in Repository Settings so you name the branch up front.
• Click the branch name in the toolbar to rename it after creation.
• Add instructions to your AGENTS.md to have the agent rename the branch before starting work.

# Add to AGENTS.md to make agents rename generic branches:
Before you start your task, check the current git branch name.
If it is something generic like an animal name, rename the branch
to match your task. Example: git branch -m feat/add-user-auth
Do not rename main, develop, or staging.

Archive aggressively, delete deliberately

If you're not 100% sure a branch's work is fully done or fully merged, archive it. Archiving is reversible — it just removes the worktree from the active list. Deletion removes the directory from disk and cannot be undone without the git branch still existing.

Use the run script for repeated commands

Every time you type the same command in multiple worktrees, that's a signal to put it in the Repository Commands run script. ⌘ R is faster than your shell history across worktrees.

Keep setup scripts idempotent

Your setup script will run in fresh worktrees. Make sure it works cleanly from a blank slate: install dependencies before starting the agent, handle missing .env files gracefully, and don't assume anything from a previous session.

Use lazygit inside worktrees

Open a second tab in any worktree and run lazygit for a visual git interface. This lets you review your agent's changes, stage selective hunks, and manage commits without leaving Supacode.

Pin your most-used worktrees

Pinned sessions float to the top of the sidebar. Use pinning for long-running worktrees (the main dev server, a long-running agent task) to keep them accessible via ⌃ 1/⌃ 2.

Use Ghostty's native keybindings

Since Supacode uses Ghostty under the hood, any Ghostty power-user features work: custom keybindings, quick terminal actions, and vim-mode navigation if configured. Customize in ~/.config/ghostty/config.

22 Archive vs Delete

This is the most important operational distinction in Supacode. Understanding it prevents accidental data loss.

23 Frequently Asked Questions

Does Supacode work on macOS 15 or earlier?

No. Supacode requires macOS 26.0 (Tahoe) or newer. The requirement is strict — the app uses SwiftUI APIs and system frameworks that only exist in macOS 26+. There is no workaround.

Do I need GitHub CLI to use Supacode?

No. The GitHub CLI (gh) is only required for PR and CI features. Repository management, worktree creation, the built-in terminal, and agent integration all work without gh.

Can I use any AI coding agent?

Yes — any agent that runs in a terminal shell works. Claude Code, Codex, OpenCode, Aider, or custom scripts all work fine. The four natively-supported harnesses (Claude Code, Codex, OpenCode, Pi) get additional notification and CLI integration features.

How do I theme the terminal?

Edit ~/.config/ghostty/config. Supacode uses GhosttyKit for terminal rendering and inherits all of Ghostty's theming system. Changes take effect the next time a terminal opens.

Where are my worktrees stored?

Managed worktrees live under ~/.supacode/repos/<repository-name>/. You can change the location per-repository in Repository Settings.

Can I use bare repositories?

Yes. Supacode supports bare repositories — they show with a git-branch icon instead of a folder icon. Note that the copy-ignored and copy-untracked worktree creation options are disabled for bare repos.

What is the difference between archive and delete?

Archive hides the worktree from the active list but keeps it on disk and keeps the branch. Delete removes the worktree directory from disk. When uncertain, always archive first.

How do I get meaningful branch names?

Three options: (1) enable prompted worktree creation, (2) click the branch name in the toolbar to rename it, or (3) add instructions in AGENTS.md to have your agent rename branches before starting work.

Can I run Supacode alongside Ghostty?

Yes. Both use GhosttyKit and share ~/.config/ghostty/config for theming, so your font and color settings are consistent between them. They're separate apps and can run simultaneously.

Is Supacode free?

Yes — Supacode is free and open source. There is no paid tier. The source code is at github.com/supabitapp/supacode. It uses a custom license (not a standard SPDX open-source license), so review the LICENSE file before using in commercial contexts.

How do I report a bug or request a feature?

Open an issue at github.com/supabitapp/supacode/issues. The maintainer prefers detailed written issues over unreviewed pull requests.

How do sessions persist when I quit Supacode?

Supacode bundles a ZMX multiplexer. When you quit the app, any running processes (agents, dev servers, etc.) keep running in background ZMX sessions. When you relaunch, Supacode reattaches to those sessions and restores your tabs, splits, and scroll state as if you never quit.