gwq CLI
A git worktree CLI with a fuzzy finder: one folder per branch so several agents can work in parallel without conflicts
- 475 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- Commands create and delete worktrees and branches, and remove with a flag forces deletion of an unmerged branch
- `gwq exec` and `gwq tmux run` run arbitrary commands in the chosen folders
Install
- Works in
Manual install
brew install d-kuro/tap/gwqHomebrew for macOS and Linux.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Commands create and delete worktrees and branches, and remove with a flag forces deletion of an unmerged branch
- `gwq exec` and `gwq tmux run` run arbitrary commands in the chosen folders
This is third-party code. Review the repository files before installing.
What it does
gwq manages git worktrees the way ghq manages repository clones. A worktree puts a branch in its own folder, so one repository can hold several branches at once. For AI agents this is convenient: each agent gets its own working folder, and parallel tasks do not collide in files. The main commands: `gwq add -b feature/x` creates a worktree with a new branch, `gwq list` and `gwq status` show all worktrees and the state of changes, `gwq get` returns a path for `cd $(gwq get name)`, `gwq exec` runs a command in the chosen worktree, and `gwq remove` deletes one along with its branch on request. Branches and worktrees are picked with a fuzzy finder. The `gwq status --watch` mode refreshes the table in real time and shows what the agents are doing in each folder. gwq finds worktrees across all repositories under a base directory from its configuration, with no separate registry. For long processes there is `gwq tmux`: a command starts in a persistent tmux session you can attach to later. It supports tab completion for bash, zsh and fish and shell integration for `gwq cd`.
Who it is for. For developers who run several agents (Claude Code, Codex, Cursor) on different tasks in one repository and want their working folders isolated.
Good fit when
- Three tasks on one repository with an agent for each: `gwq add -b` creates three separate folders
- You need to run tests on another branch without touching current work: `gwq exec feature -- npm test`
- You want one screen showing which worktrees have uncommitted changes: `gwq status --watch`
- Code is reviewed on a neighboring branch while you keep developing on the main one
- A long dev server or build should live in its own tmux session you can return to
Not a fit when
- There is a single task and no need for parallel branches: plain git checkout is enough
- You work in PowerShell and want shell integration: it is not supported there at the moment
- You need an agent session manager that launches Claude Code and Codex from a UI: gwq manages only worktrees and tmux
- Agents edit the same files: worktrees isolate folders, but merging the branches is still up to you
Example request
Create three worktrees with gwq for the authentication, charts and login bug tasks and start Claude Code in eachLimitations
The tool does not start agents itself: it creates folders for them and shows their state. Shell integration for `gwq cd` and `gwq add -s` works with bash, zsh and fish and is not supported in PowerShell. Some behavior (such as auto-cd after creation) is switched on by configuration options: `cd.launch_shell` and `cd.auto_cd_on_add`. The `gwq remove -b --force-delete-branch` command deletes even an unmerged branch, so `--dry-run` is worth running first. `gwq tmux` needs tmux installed. Configuration lives in a user file, and a local `.gwq.toml` in the project overrides it. A worktree isolates files but does not isolate databases, ports and shared services that agents use at the same time.
How to disable. Remove unneeded worktrees with `gwq remove`, then the binary: `brew uninstall gwq` or delete the file from `$GOPATH/bin`. Configuration lives in a user file, and a local `.gwq.toml` can be deleted from the project.
FAQ
How do I install gwq?
With Homebrew: `brew install d-kuro/tap/gwq`. Or with Go: `go install github.com/d-kuro/gwq/cmd/gwq@latest`. You can also build from source: clone the repository and run `go build -o gwq ./cmd/gwq`.
Why use worktrees with several agents?
Each worktree has its own working folder with isolated files. Agents started in different folders do not collide at the file level, while sharing the same history and repository. The author recommends this for independent tasks, parallel migrations and code review.
How do I move into a worktree?
With `cd $(gwq get name)` or `gwq cd`, which launches a new shell in the folder. If you set `cd.launch_shell = false` and add shell integration, `gwq cd` changes the directory in the current shell. The `-g` flag searches worktrees across all repositories.
Can I watch changes in all worktrees at once?
Yes, `gwq status` prints a table, `--watch` refreshes it automatically, `--filter changed` keeps only folders with changes and `--sort activity` sorts by activity. Output is available as JSON and CSV.
What does gwq tmux do?
It starts a command in a persistent tmux session, for example `gwq tmux run --id dev-server "npm run dev"`. You can then list sessions with `gwq tmux list`, attach with `gwq tmux attach dev-server` and end one with `gwq tmux kill`.
Discussion
No questions or reviews yet.
Related
CLI toolsThe GitHub CLI extension gh stack and an agent skill: a chain of dependent branches and PRs with rebase, submit and merge of the whole stack
A CLI that opens a local git diff in the browser like GitHub's Files changed tab; comments copy out as prompts for an agent
A terminal diff viewer: all files in one stream, and an agent with the hunk-review skill walks through the changes and leaves line comments
CCManager is a session manager for Claude Code, Codex, Gemini CLI and other agents: each runs in its own Git worktree with status and hooks
Indexes a codebase into a knowledge graph and gives the agent call chains, change blast radius and code search over MCP
Desktop environment for running Codex, Claude Code, OpenCode and Pi in parallel git worktrees, with a mobile companion
README in short
The README explains the idea (manage worktrees the way ghq manages clones), gives a scenario with parallel agents and three install routes. It then walks through the add, list, get, cd, exec, remove, status, tmux, config and prune commands with flags, global worktree management, shell integration and tab completion. It ends with a setup that combines ghq and fzf and a link to an article about an agent-friendly environment.