Treebeard

Treebeard is a macOS desktop app for managing Git worktrees across repositories, with built-in Codex session support and quick launch actions for common tools.

Features

• Manage worktrees across multiple repositories from one dashboard
• Search and filter worktrees by branch or path
• Drag and drop repository sections to reorder them
• Show Jira issue badges parsed from branch names
• Show GitHub PR status and CI check status per branch
• Show dirty status (+/- lines, unpushed, unpulled commits)
• Launch worktrees in VS Code, Ghostty, or Codex Desktop
• Run embedded Codex sessions directly inside Treebeard
• Create and delete worktrees directly from the app
• Built-in auto-update support for packaged releases

Prerequisites

To use the packaged app

• macOS
• Git

Optional (feature-dependent)

• GitHub CLI (gh) for PR and CI badges
• Jira CLI (jira) for Jira badges
• VS Code (code command available in PATH) for the VS Code launch button
• Ghostty for the terminal launch button
• Codex CLI/Desktop for embedded Codex sessions and Codex launch actions

Treebeard works without optional CLIs, but related badges/actions are unavailable.

To develop Treebeard

• Bun

Getting Started

bun install
bun run dev

Using Codex

Enable Codex in Settings to turn on Treebeard's worktree-level Codex actions.

• Use the Codex button on a worktree card to open an embedded Codex session for that specific worktree inside Treebeard.
• Use the launch buttons on a worktree card to open that worktree in Codex Desktop, VS Code, or Ghostty.

Scripts

Command	Description
bun run dev	Run Treebeard in development mode
bun run build	Build a packaged app via Electrobun
bun run test	Run the Vitest suite once
bun run test:watch	Run Vitest in watch mode
bun run test:coverage	Run Vitest with V8 coverage output
bun run typecheck	Run TypeScript type-checking (tsc --noEmit)
bun run start:packaged	Open the packaged app from build/stable-macos-arm64/Treebeard.app
bun run screenshot	Launch packaged app and capture treebeard-current.png

bun run screenshot auto-captures the Treebeard window when Accessibility permissions are available, and falls back to manual window selection when they are not.

Architecture

Treebeard is built with Electrobun:

• Bun-powered main process (src/bun/)
• React renderer in the main view (src/mainview/, src/components/, src/hooks/)
• Typed RPC between renderer and main process (src/shared/rpc-types.ts)
• Shared app/domain types in src/shared/types.ts
• Local config, dependency checks, and Codex runtime/session orchestration in the Bun process

High-level structure:

src/
  bun/         # main process + services (git, github, jira, launcher, config)
  mainview/    # renderer entrypoint and view shell
  components/  # UI components
  hooks/       # renderer data hooks
  shared/      # shared types and RPC schema

Configuration

App settings are persisted at:

~/.config/treebeard/treebeard-config.json

This file stores repository paths, polling interval, update settings, Codex settings, and collapsed repo state.

Contributing

See CONTRIBUTING.md for development setup, coding guidelines, and pull request expectations.

License

MIT