Worktree Ghostty Smart

Opens a smart 3-panel Ghostty terminal layout when creating worktrees, with Claude Code, lazygit, and yazi in an integrated development view.

When to Use This Hook

Attach this hook when you need to:

• Automatically create an organized multi-panel terminal layout when entering a new git worktree for focused feature development
• Get instant access to lazygit for git operations and yazi for file browsing alongside Claude Code in a single Ghostty window
• Maintain clean worktree isolation with sibling directory placement and automatic cleanup when the worktree is removed

Consider alternatives when:

• You do not use Ghostty as your terminal emulator and need a solution compatible with iTerm2, Kitty, or other terminals
• You prefer to manage your terminal layout manually or use a terminal multiplexer like tmux that has its own layout system

Quick Start

Configuration

Copy
name: worktree-ghostty-smart
type: hook
trigger: WorktreeCreate, WorktreeRemove
category: development-tools

Example Trigger

Copy
# Claude creates a worktree:
/worktree feature-auth
# Hook fires and creates 3-panel layout

Example Output

Worktree Ghostty Layout: Creating workspace
Worktree: ../worktrees/my-repo/feature-auth/
Layout:
  Left panel (60%): Claude Code session
  Top-right panel (40%): lazygit
  Bottom-right panel (40%): yazi file browser
Ghostty splits: Created successfully
All panels active and focused on worktree directory

[On worktree removal]
Worktree Ghostty Layout: Cleaning up
Worktree removed: ../worktrees/my-repo/feature-auth/
Layout: Panels closed

Core Concepts

Ghostty Layout Overview

Aspect	Details
Terminal	Ghostty terminal emulator (macOS only)
Panel Layout	3-panel: Claude Code (left), lazygit (top-right), yazi (bottom-right)
Worktree Location	Sibling directory at ../worktrees/<repo>/<name>/
Dependencies	jq, Ghostty, lazygit, yazi must be installed
Keybindings	Requires super+d (split right) and super+shift+d (split down)
Cleanup	Worktree directory and panels removed on WorktreeRemove event

Layout Creation Workflow

WorktreeCreate Event
    |
    v
[worktree-ghostty.sh invoked]
    |
    v
[Create worktree at ../worktrees/<repo>/<name>/]
    |
    v
[Open Ghostty split: super+d (right panel)]
    |
    v
[Launch lazygit in right panel]
    |
    v
[Open Ghostty split: super+shift+d (bottom-right)]
    |
    v
[Launch yazi in bottom-right panel]
    |
    v
[All three panels active]
    |
    ... (development session) ...
    |
WorktreeRemove Event
    |
    v
[Close lazygit and yazi panels]
    |
    v
[Remove worktree directory]
    |
    v
[Return to original layout]

Configuration

Parameter	Type	Default	Description
worktree_base	string	../worktrees/	Base directory for creating worktrees relative to the repository
ghostty_split_right	string	super+d	Ghostty keybinding for creating a right split panel
ghostty_split_down	string	super+shift+d	Ghostty keybinding for creating a bottom split panel
right_panel_tool	string	lazygit	Tool to launch in the top-right panel
bottom_panel_tool	string	yazi	Tool to launch in the bottom-right panel

Best Practices

1. Install all dependencies before first use - Verify that Ghostty, lazygit, yazi, and jq are all installed and available in your PATH. The hook will fail silently if any dependency is missing. Run which ghostty lazygit yazi jq to confirm availability.

2. Configure Ghostty keybindings explicitly - Add the required keybindings to your Ghostty configuration file. The hook relies on super+d for right splits and super+shift+d for down splits. Without these keybindings, the layout creation will fail.

3. Use the sibling directory pattern for clean separation - The hook creates worktrees in a sibling directory rather than inside the repository. This prevents worktree files from appearing in the main repository's file listings and keeps the workspace organized.

4. Practice the cleanup workflow - When you finish with a worktree, use the WorktreeRemove event to clean up both the directory and the terminal panels. Manually removing the directory without triggering the hook will leave orphaned Ghostty panels.

5. Customize panel tools for your workflow - While lazygit and yazi are excellent defaults, you can modify the hook script to launch different tools. For example, replace yazi with a test runner or replace lazygit with a different git client based on your preferences.

Common Issues

1. Ghostty splits do not open - The keybindings super+d and super+shift+d must be explicitly configured in Ghostty's config file. Check your Ghostty configuration at ~/.config/ghostty/config and add the required keybinding entries if they are missing.

2. Worktree creation fails with "already exists" error - If a previous worktree was not cleaned up properly, the target directory may still exist. Remove the stale worktree directory manually with rm -rf ../worktrees/<repo>/<name> before creating a new one.

3. Hook does not work on Linux - The current implementation is macOS only, using macOS-specific AppleScript and Ghostty integrations. Linux support requires community contributions to adapt the terminal management commands for Linux Ghostty or alternative terminal emulators.