gwq - Git Worktree Manager

gwq is a CLI tool for efficiently managing Git worktrees. Like how ghq manages repository clones, gwq provides intuitive operations for creating, switching, and deleting worktrees using a fuzzy finder interface.

Why gwq?

Git worktrees allow you to check out multiple branches from the same repository into separate directories. This is particularly powerful when:

• Working on multiple features simultaneously
• Running parallel AI coding agents on different tasks
• Reviewing code while developing new features
• Testing changes without disrupting your main workspace

AI Coding Agent Workflows

One of the most powerful applications of gwq is enabling parallel AI coding workflows. Instead of having a single AI agent work sequentially through tasks, you can leverage multiple worktrees to have multiple AI agents work on different parts of your project simultaneously:

# Create worktrees for parallel development
gwq add -b feature/authentication
gwq add -b feature/data-visualization
gwq add -b bugfix/login-issue

# Each AI agent can work in its own worktree
cd $(gwq get authentication) && claude
cd $(gwq get visualization) && claude
cd $(gwq get login) && claude

# Monitor all agent activity in real-time
gwq status --watch

Since each worktree has its own working directory with isolated files, AI agents can work at full speed without merge conflicts. This approach is ideal for independent tasks, parallel migrations, and code review workflows.

Installation

Homebrew (macOS/Linux)

brew install d-kuro/tap/gwq

Using Go

go install github.com/d-kuro/gwq/cmd/gwq@latest

From Source

git clone https://github.com/d-kuro/gwq.git
cd gwq
go build -o gwq ./cmd/gwq

Quick Start

# Create a new worktree with new branch
gwq add -b feature/new-ui

# List all worktrees
gwq list

# Check status of all worktrees
gwq status

# Get worktree path (for cd)
cd $(gwq get feature)

# Execute command in worktree
gwq exec feature -- npm test

# Remove a worktree
gwq remove feature/old-ui

Features

• Fuzzy Finder Interface: Built-in fuzzy finder for intuitive branch and worktree selection
• Global Worktree Management: Access all your worktrees across repositories from anywhere
• Status Dashboard: Monitor all worktrees' git status, changes, and activity at a glance
• Tmux Integration: Run and manage long-running processes in persistent tmux sessions
• Tab Completion: Full shell completion support for branches, worktrees, and configuration

Commands

gwq add

Create a new worktree.

# Create worktree with new branch
gwq add -b feature/new-ui

# Create from existing branch
gwq add main

# Interactive branch selection
gwq add -i

# Stay in worktree directory after creation
gwq add -s feature/new-ui

Flags: -b (new branch), -i (interactive), -s (stay), -f (force)

gwq list (alias: ls)

Display all worktrees.

# Simple list
gwq list
gwq ls

# Detailed information
gwq list -v

# JSON format
gwq list --json

# Show all worktrees globally
gwq list -g

Flags: -v (verbose), -g (global), --json

gwq get

Get worktree path. Useful for shell command substitution.

# Get path and change directory
cd $(gwq get feature)

# Get from global worktrees
gwq get -g myapp:feature

Flags: -g (global), -0 (null-terminated)

gwq cd

Change to worktree directory by launching a new shell.

# Change to a worktree
gwq cd feature

# Interactive selection
gwq cd

Flags: -g (global)

Note: By default, gwq cd launches a new shell. Set cd.launch_shell = false to change directory in the current shell instead. This requires shell integration — see Shell Integration for setup. PowerShell is currently not supported for shell integration.

gwq exec

Execute command in worktree directory.

# Run tests in feature branch
gwq exec feature -- npm test

# Stay in directory after command
gwq exec -s feature -- npm install

Flags: -g (global), -s (stay)

gwq remove

Delete a worktree.

# Interactive selection
gwq remove

# Delete by pattern
gwq remove feature/old

# Also delete the branch
gwq remove -b feature/completed

# Force delete unmerged branch
gwq remove -b --force-delete-branch feature/abandoned

# Preview deletion
gwq remove --dry-run feature/old

Flags: -f (force), -b (delete branch), --force-delete-branch, -g (global), --dry-run

gwq status

Monitor the status of all worktrees.

# Table view
gwq status

# Watch mode (auto-refresh)
gwq status --watch

# Filter by status
gwq status --filter changed

# Sort by activity
gwq status --sort activity

# Output formats
gwq status --json
gwq status --csv

Flags: -w (watch), -f (filter), -s (sort), -v (verbose), -g (global), --json, --csv

gwq tmux

Manage tmux sessions for long-running processes.

# List sessions
gwq tmux list

# Run command in new session
gwq tmux run "npm run dev"

# Run with custom ID
gwq tmux run --id dev-server "npm run dev"

# Attach to session
gwq tmux attach dev-server

# Kill session
gwq tmux kill dev-server

gwq config

Manage configuration.

# Show configuration
gwq config list

# Set global value (default)
gwq config set worktree.basedir ~/worktrees

# Set local value (writes to .gwq.toml in current directory)
gwq config set --local finder.preview false

# Get value
gwq config get worktree.basedir

Flags: --local (write to local config instead of global)

gwq prune

Clean up deleted worktree information.

gwq prune

Global Worktree Management

gwq automatically discovers all worktrees in your configured base directory:

• Outside Git Repositories: Shows all worktrees in the base directory
• Inside Git Repositories: Shows only worktrees for the current repository (use -g to see all)
• No Registry Required: Uses filesystem scanning instead of maintaining a separate registry

Shell Integration

The completion scripts provide both tab completion and gwq cd shell integration. When cd.launch_shell is set to false, the completion script includes a shell wrapper that allows gwq cd to change the directory in the current shell without launching a new shell. PowerShell is currently not supported for shell integration.

Tab Completion

Bash:

source <(gwq completion bash)

Zsh:

source <(gwq completion zsh)

Fish:

gwq completion fish > ~/.config/fish/completions/gwq.fish

PowerShell:

gwq completion powershell | Out-String | Invoke-Expression

Configuration

Configuration Files

gwq uses two configuration files:

| File | Location | Purpose | | ------ | ------------------------------- | --------------------------------- | | Global | ~/.config/gwq/config.toml | Default settings for all projects | | Local | .gwq.toml (current directory) | Project-specific overrides |

Local configuration takes precedence over global settings.

Example global config (~/.config/gwq/config.toml):

[worktree]
basedir = "~/worktrees"
auto_mkdir = true

[finder]
preview = true

[naming]
template = "{{.Host}}/{{.Owner}}/{{.Repository}}/{{.Branch}}"
sanitize_chars = { "/" = "-", ":" = "-" }

[cd]
launch_shell = false  # Use shell integration instead of launching a new shell

[ui]
icons = true
tilde_home = true

[[repository_settings]]
repository = "~/src/myproject"
copy_files = ["templates/.env.example"]
setup_commands = ["npm install"]

Key Settings

| Setting | Description | Default | | ------------------ | ------------------------------------- | -------------------------------------------------- | | worktree.basedir | Base directory for worktrees | ~/worktrees | | naming.template | Directory naming template | {{.Host}}/{{.Owner}}/{{.Repository}}/{{.Branch}} | | ui.tilde_home | Display ~ instead of full home path | true | | cd.launch_shell | Launch a new shell for gwq cd (set false for shell integration) | true | | ui.icons | Show icons in output | true |

Per-Repository Setup

Configure automatic file copying and setup commands per repository. These settings can be defined in both global and local configuration files.

[[repository_settings]]
repository = "~/src/myproject"
copy_files = ["templates/.env.example", "config/*.json"]
setup_commands = ["npm install", "npm run setup"]

Merge Behavior

When both global and local configs define repository_settings, they are merged using the repository field as the key:

• Same repository: Local settings completely override global
• Different repositories: Both are kept

Example:

Global config (~/.config/gwq/config.toml):

[[repository_settings]]
repository = "~/src/project-a"
setup_commands = ["npm install"]

[[repository_settings]]
repository = "~/src/project-b"
setup_commands = ["go mod download"]

Local config (.gwq.toml):

[[repository_settings]]
repository = "~/src/project-a"
setup_commands = ["yarn install", "yarn build"]

[[repository_settings]]
repository = "~/src/project-c"
setup_commands = ["make setup"]

Merged result: | Repository | Source | Commands | |------------|--------|----------| | project-a | Local (override) | yarn install, yarn build | | project-b | Global | go mod download | | project-c | Local (new) | make setup