Hatchet

A TUI for managing work via Fizzy and Git worktrees with automatic database cloning for Rails projects.

Installation

Arch Linux (AUR)

yay -S hatchet

From Source

Requires Bun.

git clone https://github.com/ryanrhughes/hatchet.git
cd hatchet
bun install
make install

make install builds a standalone binary and installs it to /usr/bin/hatchet by default, along with the Chrome extension assets under /usr/share/hatchet. Override install paths with standard Make variables:

make install PREFIX=/usr/local
make local-install       # installs under ~/.local
make uninstall
make check               # typecheck, test, and build

For development without installing:

bun hatchet

Shell Alias

Add an ht alias for quick access:

Bash

Add to ~/.bashrc:

alias ht="hatchet"

Zsh

Add to ~/.zshrc:

alias ht="hatchet"

Fish

Create ~/.config/fish/conf.d/hatchet.fish:

alias ht="hatchet"

From Source

If running from source, point the alias to bun:

# Bash/Zsh
alias ht="bun ~/path/to/hatchet/src/main.ts"

# Fish (~/.config/fish/conf.d/hatchet.fish)
alias ht="bun ~/path/to/hatchet/src/main.ts"

Features

• Create, switch, and remove Git worktrees
• Launch multiple tools (configured AI harness via omarchy-launch-ai, NeoVim, Terminal) in your worktree
• Automatic SQLite database cloning for Rails projects
• Copies environment files (.env.local, config/master.key, etc.)
• Fizzy integration for task management (via fizzy-cli)
• GitHub PR review worktrees that locally merge a PR onto the latest base branch

Keybinds

From the main screen, use these shortcuts to quickly launch tools in the selected worktree's folder:

Key	Action
c	Open configured AI harness
t	Open shell here
n	Open NeoVim
Shift + c	Open configured AI harness in a new terminal
Shift + t	Open new terminal window
Shift + n	Open NeoVim in a new window

Tip: Combine shortcuts for a multi-tool workflow. For example, Shift + n followed by c opens NeoVim in a new window and your AI harness in the current terminal, giving you both in the same context.

Deleting Worktrees

Fizzy Integration

Hatchet integrates with Fizzy for task management. To use Fizzy features, install fizzy-cli and run fizzy setup.

Once configured, Hatchet can:

• Display your Fizzy boards and cards
• Create worktrees directly from Fizzy cards
• Change worktrees for easy context switching
• Seed AI harness sessions with Fizzy card details

Tip: Set your board in your project's .fizzy.yaml to skip board selection.

Create Worktrees from Fizzy Cards

With fizzy-cli, you're able to create worktrees directly from cards in Fizzy without leaving Hatchet.

Load Context from Fizzy

When a worktree is created from Fizzy, you'll be given the option to include the contents of the card when launching your configured AI harness to assist in getting you started even faster!

GitHub PR Review Mode

Hatchet can create a disposable review worktree for a pull request as it would merge into the latest fetched base branch. This is useful when the PR branch is stale but you want to review the real merge result without updating or pushing the author's branch.

# Review PR #456 against latest base
hatchet --review-pr 456 --path /home/user/myproject

# Review and launch your configured AI harness with the merge summary preloaded
hatchet --review-pr 456 --path /home/user/myproject --launch-ai --with-context

Review mode creates a local branch/worktree like:

../myproject.review-pr-456
hatchet/review-pr-456

It also writes .hatchet/review.md in the review worktree with merge status, base-branch advancement, changed-file overlap, conflicts, and useful review commands. In the TUI's Pull Requests list, press r on a PR to create this latest-base review worktree.

Project Registry

Hatchet can be launched outside a repository and used as a project picker. Register projects globally in ~/.config/hatchet/projects.jsonc with the CLI:

# Register an existing checkout
hatchet --add-repo herald --repo-path ~/Work/herald

# Register a repo URL; Hatchet clones it on first use if the path is missing
hatchet --add-repo nebula --clone-repo git@github.com:org/nebula.git

# Use a registered project non-interactively
hatchet --repo herald --card 123 -o --with-context
hatchet --repo nebula --pr 456 -o

# List registered projects
hatchet --list-repos

When you run hatchet outside a git repo, the TUI starts from this registered project list.

Browser Extension

The Hatchet Chrome extension adds an "Open in Hatchet" button to Fizzy, allowing you to create or switch to a worktree directly from your browser.

Installation

1. Install the protocol handler:

   hatchet --install-handler

2. Install the Chrome extension:

   • Open chrome://extensions
   • Enable Developer mode
   • Click Load unpacked
   • Select /usr/share/hatchet/chrome-extension (or chrome-extension/ if running from source)

Configuration

The first time you click the Hatchet button on a board, you'll be prompted to enter the project path. This maps the Fizzy board to your local git repository.

You can also manage board-to-path mappings in the extension popup:

How It Works

1. Click the Hatchet button on any Fizzy card
2. A terminal opens and creates/switches to a worktree for that card
3. Your configured AI harness launches with the card context pre-loaded
4. When you exit, you're dropped into a bash shell in the worktree

Rails Database Cloning

When creating a worktree in a Rails project with SQLite, Hatchet automatically:

1. Parses config/database.yml directly (no Rails environment needed)
2. Finds all SQLite database files including:
   • Standard databases (db/development.sqlite3, storage/*.sqlite3)
   • Multi-tenant databases with %{tenant} patterns
   • WAL and SHM files for consistency
3. Copies everything to the new worktree

Supported database.yml Patterns

# Single database (older Rails)
development:
  adapter: sqlite3
  database: db/development.sqlite3

# Multi-database (Rails 6+)
development:
  primary:
    <<: *default
    database: storage/development.sqlite3
  cache:
    <<: *default
    database: storage/cache.sqlite3

# Multi-tenant (acts_as_tenant style)
development:
  primary:
    <<: *default
    database: storage/tenants/development/%{tenant}/main.sqlite3
    tenanted: true

Files Copied Automatically

These files are copied from the main repo to the worktree if they exist:

• .env.local
• .env.development.local
• config/master.key
• config/credentials/development.key

Running Multiple Worktrees

Port Assignment

Each worktree needs its own port. Add this bin/dev script to your Rails project for automatic port assignment:

#!/usr/bin/env ruby
require 'socket'

def find_free_port(start_port = 3000)
  port = start_port
  loop do
    begin
      TCPServer.new('127.0.0.1', port).close
      return port
    rescue Errno::EADDRINUSE
      port += 1
    end
  end
end

port = find_free_port
puts "Starting on port #{port}..."
exec "./bin/rails", "server", "-p", port.to_s, *ARGV

Each worktree automatically gets the next available port (3000, 3001, 3002, etc.).

Session Isolation

When running multiple worktrees on different ports, they share the same session cookie (same localhost domain). Logging into one worktree logs you out of another.

Solution: Use separate browser profiles or private/incognito windows for each worktree.

Configuration

Hatchet supports configuration via JSONC files (JSON with comments). Config is loaded from:

1. .hatchet.jsonc in the project folder (repo root) - project-specific
2. ~/.config/hatchet/config.jsonc - global config

Project config takes precedence over global config.

Available Options

{
  // Skip copying SQLite databases when creating worktrees
  "skipDatabaseCopy": false,
  // Skip copying environment files (.env.local, master.key, etc.)
  "skipEnvCopy": false,
  // Command used for `c` / `--launch-ai`; defaults to omarchy-launch-ai
  "aiCommand": "omarchy-launch-ai",
  // Editor command for `n`; defaults to $VISUAL, $EDITOR, then nvim
  "editorCommand": "nvim",
  // Optional dev command shown in metadata for future launch flows
  "devCommand": "bin/dev",
  // Setup commands run after new worktree creation
  "setupCommands": ["bundle install", "bin/rails db:prepare"],
  // Additional files to copy when creating worktrees
  "additionalFilesToCopy": ["special_file", "config/custom.yml"]
}

Hatchet writes per-worktree metadata to .hatchet/meta.json and excludes .hatchet/ from the worktree's Git status. Metadata records the source card/PR/manual branch, copied files, setup status, and launch commands.