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.

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

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.

brew install d-kuro/tap/gwq

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

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

# 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

• 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

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)

Display all worktrees.

# Simple list
gwq list

# Detailed information
gwq list -v

# JSON format
gwq list --json

# Show all worktrees globally
gwq list -g

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

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)

Change to worktree directory by launching a new shell.

# Change to a worktree
gwq cd feature

# Interactive selection
gwq cd

Flags: -g (global)

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)

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

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

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

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)

Clean up deleted worktree information.

gwq prune

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

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

gwq uses two configuration files:

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 = { "/" = "-", ":" = "-" }

[ui]
icons = true
tilde_home = true

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

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"]

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:

For a powerful development workflow, you can integrate gwq with ghq (repository manager) and fzf (fuzzy finder). This combination is particularly effective for parallel AI coding agent workflows.

The key idea is to place worktrees alongside your cloned repositories under the same root directory, enabling unified fuzzy search across both. This consolidates all your development directories into a single searchable location.

For detailed configuration and shell function setup, see: A Coding-Agent-Friendly Environment Is Friendly to Humans Too: ghq x gwq x fzf

gwq organizes worktrees using a URL-based hierarchy:

~/worktrees/
├── github.com/
│   └── user/
│       └── myapp/
│           ├── feature-auth/
│           └── feature-api/
└── gitlab.com/
    └── company/
        └── project/
            └── feature-x/

This structure prevents naming conflicts and preserves context about which repository a worktree belongs to.

• Git 2.5+ (for worktree support)
• Go 1.24+ (for building from source)

Apache License 2.0 - see LICENSE file for details.