{"id":29213749,"url":"https://github.com/d-kuro/gwq","last_synced_at":"2026-05-01T03:05:44.268Z","repository":{"id":295625904,"uuid":"990591750","full_name":"d-kuro/gwq","owner":"d-kuro","description":"🌳 Git worktree manager with fuzzy finder - Work on multiple branches simultaneously, perfect for parallel AI coding workflows 🍋","archived":false,"fork":false,"pushed_at":"2026-04-29T17:52:36.000Z","size":1456,"stargazers_count":402,"open_issues_count":5,"forks_count":16,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-29T19:33:00.815Z","etag":null,"topics":["ai","coding-agent","git","go"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d-kuro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-26T10:48:05.000Z","updated_at":"2026-04-29T17:50:11.000Z","dependencies_parsed_at":"2025-06-16T01:33:54.637Z","dependency_job_id":"867b6d0c-b9c7-4a04-b4ee-94a576dbf634","html_url":"https://github.com/d-kuro/gwq","commit_stats":null,"previous_names":["d-kuro/wtree","d-kuro/gwq"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/d-kuro/gwq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-kuro%2Fgwq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-kuro%2Fgwq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-kuro%2Fgwq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-kuro%2Fgwq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d-kuro","download_url":"https://codeload.github.com/d-kuro/gwq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-kuro%2Fgwq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32483434,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","coding-agent","git","go"],"created_at":"2025-07-02T23:02:08.632Z","updated_at":"2026-05-01T03:05:44.258Z","avatar_url":"https://github.com/d-kuro.png","language":"Go","funding_links":[],"categories":["Go","Development Workflows \u0026 Agents"],"sub_categories":["Other IDEs"],"readme":"# gwq - Git Worktree Manager\n\n`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.\n\n![](./docs/assets/usage.gif)\n\n## Why gwq?\n\nGit worktrees allow you to check out multiple branches from the same repository into separate directories. This is particularly powerful when:\n\n- Working on multiple features simultaneously\n- Running parallel AI coding agents on different tasks\n- Reviewing code while developing new features\n- Testing changes without disrupting your main workspace\n\n### AI Coding Agent Workflows\n\nOne 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:\n\n```bash\n# Create worktrees for parallel development\ngwq add -b feature/authentication\ngwq add -b feature/data-visualization\ngwq add -b bugfix/login-issue\n\n# Each AI agent can work in its own worktree\ncd $(gwq get authentication) \u0026\u0026 claude\ncd $(gwq get visualization) \u0026\u0026 claude\ncd $(gwq get login) \u0026\u0026 claude\n\n# Monitor all agent activity in real-time\ngwq status --watch\n```\n\nSince 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.\n\n## Installation\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew install d-kuro/tap/gwq\n```\n\n### Using Go\n\n```bash\ngo install github.com/d-kuro/gwq/cmd/gwq@latest\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/d-kuro/gwq.git\ncd gwq\ngo build -o gwq ./cmd/gwq\n```\n\n## Quick Start\n\n```bash\n# Create a new worktree with new branch\ngwq add -b feature/new-ui\n\n# List all worktrees\ngwq list\n\n# Check status of all worktrees\ngwq status\n\n# Get worktree path (for cd)\ncd $(gwq get feature)\n\n# Execute command in worktree\ngwq exec feature -- npm test\n\n# Remove a worktree\ngwq remove feature/old-ui\n```\n\n## Features\n\n- **Fuzzy Finder Interface**: Built-in fuzzy finder for intuitive branch and worktree selection\n- **Global Worktree Management**: Access all your worktrees across repositories from anywhere\n- **Status Dashboard**: Monitor all worktrees' git status, changes, and activity at a glance\n- **Tmux Integration**: Run and manage long-running processes in persistent tmux sessions\n- **Tab Completion**: Full shell completion support for branches, worktrees, and configuration\n\n## Commands\n\n### `gwq add`\n\nCreate a new worktree.\n\n```bash\n# Create worktree with new branch\ngwq add -b feature/new-ui\n\n# Create from existing branch\ngwq add main\n\n# Interactive branch selection\ngwq add -i\n\n# Stay in worktree directory after creation\ngwq add -s feature/new-ui\n```\n\n**Flags**: `-b` (new branch), `-i` (interactive), `-s` (stay), `-f` (force)\n\n\u003e **Note**: With shell integration and `cd.launch_shell = false`, `-s` changes the current shell's directory instead of spawning a nested shell. Set `cd.auto_cd_on_add = true` to auto-cd after every `gwq add` without `-s`.\n\n### `gwq list` (alias: `ls`)\n\nDisplay all worktrees.\n\n```bash\n# Simple list\ngwq list\ngwq ls\n\n# Detailed information\ngwq list -v\n\n# JSON format\ngwq list --json\n\n# Show all worktrees globally\ngwq list -g\n```\n\n**Flags**: `-v` (verbose), `-g` (global), `--json`\n\n### `gwq get`\n\nGet worktree path. Useful for shell command substitution.\n\n```bash\n# Get path and change directory\ncd $(gwq get feature)\n\n# Get from global worktrees\ngwq get -g myapp:feature\n```\n\n**Flags**: `-g` (global), `-0` (null-terminated)\n\n### `gwq cd`\n\nChange to worktree directory by launching a new shell.\n\n```bash\n# Change to a worktree\ngwq cd feature\n\n# Interactive selection\ngwq cd\n```\n\n**Flags**: `-g` (global)\n\n\u003e **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](#shell-integration) for setup. PowerShell is currently not supported for shell integration.\n\n### `gwq exec`\n\nExecute command in worktree directory.\n\n```bash\n# Run tests in feature branch\ngwq exec feature -- npm test\n\n# Stay in directory after command\ngwq exec -s feature -- npm install\n```\n\n**Flags**: `-g` (global), `-s` (stay)\n\n### `gwq remove`\n\nDelete a worktree.\n\n```bash\n# Interactive selection\ngwq remove\n\n# Delete by pattern\ngwq remove feature/old\n\n# Also delete the branch\ngwq remove -b feature/completed\n\n# Force delete unmerged branch\ngwq remove -b --force-delete-branch feature/abandoned\n\n# Preview deletion\ngwq remove --dry-run feature/old\n```\n\n**Flags**: `-f` (force), `-b` (delete branch), `--force-delete-branch`, `-g` (global), `--dry-run`\n\n### `gwq status`\n\nMonitor the status of all worktrees.\n\n```bash\n# Table view\ngwq status\n\n# Watch mode (auto-refresh)\ngwq status --watch\n\n# Filter by status\ngwq status --filter changed\n\n# Sort by activity\ngwq status --sort activity\n\n# Output formats\ngwq status --json\ngwq status --csv\n```\n\n**Flags**: `-w` (watch), `-f` (filter), `-s` (sort), `-v` (verbose), `-g` (global), `--json`, `--csv`\n\n### `gwq tmux`\n\nManage tmux sessions for long-running processes.\n\n```bash\n# List sessions\ngwq tmux list\n\n# Run command in new session\ngwq tmux run \"npm run dev\"\n\n# Run with custom ID\ngwq tmux run --id dev-server \"npm run dev\"\n\n# Attach to session\ngwq tmux attach dev-server\n\n# Kill session\ngwq tmux kill dev-server\n```\n\n### `gwq config`\n\nManage configuration.\n\n```bash\n# Show configuration\ngwq config list\n\n# Set global value (default)\ngwq config set worktree.basedir ~/worktrees\n\n# Set local value (writes to .gwq.toml in current directory)\ngwq config set --local finder.preview false\n\n# Get value\ngwq config get worktree.basedir\n```\n\n**Flags**: `--local` (write to local config instead of global)\n\n### `gwq prune`\n\nClean up deleted worktree information.\n\n```bash\ngwq prune\n```\n\n## Global Worktree Management\n\n`gwq` automatically discovers all worktrees in your configured base directory:\n\n- **Outside Git Repositories**: Shows all worktrees in the base directory\n- **Inside Git Repositories**: Shows only worktrees for the current repository (use `-g` to see all)\n- **No Registry Required**: Uses filesystem scanning instead of maintaining a separate registry\n\n## Shell Integration\n\nThe completion scripts provide both tab completion and shell integration for `gwq cd` and `gwq add`. When `cd.launch_shell` is set to `false`, the completion script includes a shell wrapper that allows these commands to change the directory in the current shell without launching a new shell. For `gwq add`, this applies to `-s`/`--stay` and to every successful add when `cd.auto_cd_on_add = true`. PowerShell is currently not supported for shell integration.\n\n### Tab Completion\n\n**Bash:**\n\n```bash\nsource \u003c(gwq completion bash)\n```\n\n**Zsh:**\n\n```bash\nsource \u003c(gwq completion zsh)\n```\n\n**Fish:**\n\n```bash\ngwq completion fish \u003e ~/.config/fish/completions/gwq.fish\n```\n\n**PowerShell:**\n\n```powershell\ngwq completion powershell | Out-String | Invoke-Expression\n```\n\n## Configuration\n\n### Configuration Files\n\ngwq uses two configuration files:\n\n| File   | Location                        | Purpose                           |\n| ------ | ------------------------------- | --------------------------------- |\n| Global | `~/.config/gwq/config.toml`     | Default settings for all projects |\n| Local  | `.gwq.toml` (current directory) | Project-specific overrides        |\n\nLocal configuration takes precedence over global settings.\n\n**Example global config** (`~/.config/gwq/config.toml`):\n\n```toml\n[worktree]\nbasedir = \"~/worktrees\"\nauto_mkdir = true\n\n[finder]\npreview = true\n\n[naming]\ntemplate = \"{{.Host}}/{{.Owner}}/{{.Repository}}/{{.Branch}}\"\nsanitize_chars = { \"/\" = \"-\", \":\" = \"-\" }\n\n[cd]\nlaunch_shell = false  # Use shell integration instead of launching a new shell\nauto_cd_on_add = false  # Auto-cd after 'gwq add' when shell integration is active\n\n[ui]\nicons = true\ntilde_home = true\n\n[[repository_settings]]\nrepository = \"~/src/myproject\"\ncopy_files = [\"templates/.env.example\"]\nsetup_commands = [\"npm install\"]\nbasedir = \"./worktrees\"\n```\n\n### Key Settings\n\n| Setting             | Description                                                         | Default                                            |\n| ------------------- | ------------------------------------------------------------------- | -------------------------------------------------- |\n| `worktree.basedir`  | Base directory for worktrees                                        | `~/worktrees`                                      |\n| `naming.template`   | Directory naming template                                           | `{{.Host}}/{{.Owner}}/{{.Repository}}/{{.Branch}}` |\n| `ui.tilde_home`     | Display `~` instead of full home path                               | `true`                                             |\n| `cd.launch_shell`   | Launch a new shell for `gwq cd` (set `false` for shell integration) | `true`                                             |\n| `cd.auto_cd_on_add` | Auto-cd after `gwq add` when shell integration is active            | `false`                                            |\n| `ui.icons`          | Show icons in output                                                | `true`                                             |\n\n### Per-Repository Setup\n\nConfigure automatic file copying and setup commands per repository. These settings can be defined in both global and local configuration files.\n\n```toml\n[[repository_settings]]\nrepository = \"~/src/myproject\"\ncopy_files = [\"templates/.env.example\", \"config/*.json\"]\nsetup_commands = [\"npm install\", \"npm run setup\"]\nbasedir = \"./worktrees\"\n```\n\n#### Merge Behavior\n\nWhen both global and local configs define `repository_settings`, they are merged using the `repository` field as the key:\n\n- **Same repository**: Local settings completely override global\n- **Different repositories**: Both are kept\n\n**Example:**\n\nGlobal config (`~/.config/gwq/config.toml`):\n\n```toml\n[[repository_settings]]\nrepository = \"~/src/project-a\"\nsetup_commands = [\"npm install\"]\n\n[[repository_settings]]\nrepository = \"~/src/project-b\"\nsetup_commands = [\"go mod download\"]\n```\n\nLocal config (`.gwq.toml`):\n\n```toml\n[[repository_settings]]\nrepository = \"~/src/project-a\"\nsetup_commands = [\"yarn install\", \"yarn build\"]\n\n[[repository_settings]]\nrepository = \"~/src/project-c\"\nsetup_commands = [\"make setup\"]\n```\n\n**Merged result:**\n| Repository | Source | Commands |\n|------------|--------|----------|\n| `project-a` | Local (override) | `yarn install`, `yarn build` |\n| `project-b` | Global | `go mod download` |\n| `project-c` | Local (new) | `make setup` |\n\n## Advanced Usage\n\n### Unified Workflow with ghq and fzf\n\nFor a powerful development workflow, you can integrate `gwq` with [ghq](https://github.com/x-motemen/ghq) (repository manager) and [fzf](https://github.com/junegunn/fzf) (fuzzy finder). This combination is particularly effective for parallel AI coding agent workflows.\n\nThe 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.\n\nFor detailed configuration and shell function setup, see: [A Coding-Agent-Friendly Environment Is Friendly to Humans Too: ghq x gwq x fzf](https://dev.to/shunk031/a-coding-agent-friendly-environment-is-friendly-to-humans-too-ghq-gwq-fzf-2km0)\n\n## Directory Structure\n\n`gwq` organizes worktrees using a URL-based hierarchy:\n\n```\n~/worktrees/\n├── github.com/\n│   └── user/\n│       └── myapp/\n│           ├── feature-auth/\n│           └── feature-api/\n└── gitlab.com/\n    └── company/\n        └── project/\n            └── feature-x/\n```\n\nThis structure prevents naming conflicts and preserves context about which repository a worktree belongs to.\n\nWhen a per-repository `basedir` is configured, worktrees are rooted there instead of the global basedir. The path within still follows the naming template:\n\n```\n~/src/myproject/\n├── worktrees/\n│   └── github.com/\n│       └── user/\n│           └── myproject/\n│               ├── feature-auth/\n│               └── feature-api/\n└── ...\n```\n\nTo get a `\u003cbasedir\u003e/\u003crepo\u003e/\u003cbranch\u003e` structure, set `naming.template = \"{{.Repository}}/{{.Branch}}\"`. Note that `naming.template` is a global setting and affects all repositories:\n\n```\n~/src/myproject/\n├── worktrees/\n│   └── myproject/\n│       ├── feature-auth/\n│       └── feature-api/\n└── ...\n```\n\n## Requirements\n\n- Git 2.5+ (for worktree support)\n- Go 1.24+ (for building from source)\n\n## License\n\nApache License 2.0 - see [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-kuro%2Fgwq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd-kuro%2Fgwq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-kuro%2Fgwq/lists"}