name: gwm description: Manage git worktrees across any repository with the gwm Rust binary (CLI + ratatui TUI). Use when the user asks to create / list / remove / bootstrap / switch / link worktrees, run a command across worktrees (gwm exec) or reclaim build artifacts (gwm clean), materialise a PR into a worktree (gwm review), drive a multi-repo workspace (--workspace), run the JSON daemon / statusline (gwm daemon, gwm statusline), list or pin AI-agent sessions per worktree (gwm agents, Claude Code / Codex / opencode / Mistral Vibe detection), seed config from a preset (gwm init --preset), diagnose with gwm doctor, drive tmux/zellij, or wire gcd via gwm shell-init. Also covers multi-forge (#419): GitHub via gh or GitLab via glab, the forge / [forge_hosts] keys, and gwm trust add. Triggers on gwm, gwq, git worktree, .gwm.toml, forge, forge_hosts, glab, gwm trust add, GitLab MR, gwm create, gwm list, gwm exec, gwm clean, gwm review, gwm daemon, gwm statusline, gwm agents, gwm note, gwm bootstrap, gwm doctor, gwm switch, gwm tmux, gwm zellij, gwm link, gwm status, gwm shell-init, gcd, feat/#, fix/#, GitHub issue/PR linking on a worktree. allowed-tools: Bash, Read, Edit, Write

gwm: git worktree manager (Rust CLI + TUI)

Single-binary Rust tool that manages git worktrees with libgit2, a ratatui TUI, a declarative per-repo bootstrap (.gwm.toml), GitHub issue/PR linking, multiplexer hand-off (tmux / zellij), and a doctor command. Replaces project-specific bash wrappers with one portable binary that works in any git repo.

Source: https://github.com/kbrdn1/gwm-cli, latest stable 1.9.0 (machine contracts frozen since 1.0.0, MSRV 1.95).

1.9.0 is the licensing line, and it changes nothing you call. gwm is dual-licensed MIT OR Apache-2.0: MIT stays in full under LICENSE-MIT, LICENSE-APACHE joins it for its §3 patent grant, and a user picks either without having to say which. Both texts travel in every artefact (release archives, .deb, .rpm, AUR, the published crate). The libraries statically compiled in ship their notices under third-party/: libgit2 (GPLv2 with a linking exception, which is conditional on the notice travelling) and zlib. Behaviour-wise the line is what gwm prints: 165 em dashes rewritten across the binary's string literals and 49 more in gwm --help, so an error message or a completion script no longer carries a character the docs dropped; the Settings panel sizes to its active tab instead of a flat 60% of the frame; and a worktree path is spelled one way everywhere it is printed in full, ~ for $HOME, in the TUI header, the table and the sidebar alike (gwm path --format=json stays absolute).

1.8.0 is the density line, and it changes a default. The TUI is compact unless told otherwise: panes and sidebar sections carry no box rule, each is delimited by a filled one-line header (uppercase title with its bracketed key, counter pinned right on the same line), a muted rule separates the two panes, and the worktrees pane sizes itself to its row count instead of reserving a share of the split. That is two rows and two columns back per section. Focus reads on the header, which takes the focus role and the selection_bg fill, so the border is no longer the focus cue. [tui] layout = "bordered" restores gwm's pre-1.8 frames verbatim and is left untouched by the compact refinements. Two knobs ride along, both applying under either layout: [tui] status_one_line (on by default) folds the sidebar Status block onto one row joined by ·, leaving the path its own row; [tui] dim_unfocused (off) dims the inactive pane's body via the terminal's DIM attribute. A new theme role, section_bg, paints the compact header fill: an indexed colour, not a translucent white, so the mode holds up without truecolor, and distinct from selection_bg in every preset because that difference is what separates a focused header from an unfocused one. Overlays and modals keep their border either way, and their width now comes from one policy (modal_width(term_width, pct, min, max)) rather than the four it used to be, two of which got narrower as the terminal widened.

Per-worktree notes, shipped in 1.7.0 (#515). N opens the selected worktree's note in an editable modal (Esc writes and closes; Ctrl+e hands the same file to $EDITOR: editor_cmd, then $EDITOR, then vi, the handoff o uses in mode = "editor"), and the table carries a binary markdown marker (nf-oct-markdown, captioning its own column since #595) on the rows that have one. Notes are plain Markdown at <main-checkout>/.git/gwm/notes/<branch>.md: greppable with gwm shut down, never committed, and they survive gwm remove, which is why they live in the main checkout rather than in the worktree. gwm note show [slug] prints one and exits 1 when there is none; the --format=json rows carry it in an additive note field. The note is keyed on the branch, so a detached row cannot carry one (and says so), a rename moves the file, and gwm doctor reports a note whose branch is gone (not gwm clean, whose --yes only ever removes directories git already ignores). Presence means non-blank, since vi over an empty buffer writes one byte. N was unbound before, so a .gwm.toml binding a chord starting with N is now a prefix conflict refused at load time.

Security, 1.6.0 (GHSA-fffq-vg6f-gxqm, high). Every version up to and including 1.5.0 expanded lifecycle-hook placeholders into sh -c unescaped, so a branch name carrying ; / | / $ / backticks (all legal in a git ref, and a branch can arrive from someone else's push) ran arbitrary commands as the user, with no trust prompt in the path: the TOFU gate covers the repo's hooks, never the branch name flowing into them. Values are shell-escaped on expansion in 1.6.0, and hooks also get their context as GWM_* environment variables, which need no quoting at all. No backport: upgrade.

Free-form naming, shipped in 1.6.0 (#416 / #418). gwm create --name spike-redis skips the <type> <issue> <desc> triple; the name becomes the branch verbatim, so branch_pattern / path_pattern do not apply and branch-name-derived features (issue auto-linking, gitmoji) stay inactive on it, with gwm link as the way back. The TUI create and rename forms present the fields the repo's own patterns ask for, in pattern order, instead of the canonical triple, and move between the structured and free-form shapes in both directions.

Multi-forge, shipped in 1.5.0 (#419). Issue / PR lookups go through a Forge trait with two backends: GitHub via gh, GitLab via glab. forge = "github" | "gitlab" in .gwm.toml names the backend; [forge_hosts] in the user-level config authorises a self-hosted host; gwm trust add is the per-repo alternative. Worktrees, bootstrap, branch naming and link storage are forge-neutral: only the network layer knows which forge is in play. See Forge selection.

Shipped since 1.0.0: per-worktree notes (N, #515), the rich PR / issue view (I, #420 + its inline review comments #528), container execution on an exec profile (#421), multi-row selection with a batch delete (Space + d, #484), the symfony preset (#392), and a TUI delete that finally runs the remove hooks and records the undo journal (#521 / #531), all in 1.7.0; free-form naming in 1.6.0 (#416 / #418, above) alongside its security fix; multi-forge in 1.5.0 (#419, above); the help overlay (?, complete by construction: every Action must appear, #453) and a trio of TUI polish items in 1.4.0; agent session detection in 1.3.0 (#408): per-worktree AI-agent sessions (Claude Code, Codex, opencode, Mistral Vibe) read from on-disk artefacts, no process scanning, surfaced as gwm agents [attach|detach], a conditional AGENT column, an a overlay, a pinned-only Agents sidebar pane and multi-pins in branch config (gwm-agent-pin); plus the Windows daemon over a named pipe (#439). 1.0.0 shipped: gwm exec / gwm clean (#313), gwm review <PR#> (#308), the JSON API + gwm daemon + gwm statusline (#38 / #309), gwm init --preset (#37), multi-repo --workspace (#36), embedded PTY overlays (#35), a rebindable keymap incl. contextual modal keys + a live Settings panel with a Keys tab (#290 / #219 / #294), a Working Tree pane and a current-PR CI indicator (#300 / #299).

When to use this skill

• User runs or asks about any gwm <subcommand>: init (incl. --preset), list (incl. --format json), create, remove, path / cd, bootstrap, sync, prune, doctor, types, completions, shell-init, switch (alias s), tmux, zellij, link, unlink, open, status, exec, clean, review, daemon, statusline, agents, new, pr, config, history, undo, trust, labels, milestones, hooks, commit-prefix, aliases, theme, tui keys. trust takes add | list | revoke | show.
• User wants to fan a command out across worktrees (gwm exec -- <cmd>) or reclaim build artifacts (gwm clean).
• User wants to materialise a GitHub PR into a worktree to review/test it (gwm review <PR#>, cross-fork, safe-by-default).
• User wants a multi-repo workspace (gwm --workspace <dir>), the JSON API / daemon (--format=json, gwm daemon, gwm statusline for shell prompts), or stack presets (gwm init --preset laravel|node|rust|go|python-uv|generic).
• User asks which AI agents are working where: gwm agents (per-worktree sessions + an unmatched section), gwm agents attach <wt> <id> / detach <wt> [<id>] (multi-pins), the TUI a overlay (select j/k, pin a, unpin d, attach-by-id i), the pinned-only Agents sidebar pane, or the GWM_AGENTS_HOME test seam.
• User opens the TUI by running gwm alone in a repo, or the picker via gwm switch / gwm s.
• User wants to delete several worktrees at once: Space to mark rows in the TUI then d (#484), or gwm remove a b c from the shell.
• User wants to write down where they were on a worktree: N in the TUI opens its note in an editable modal (#515), gwm note show reads it back, gwm doctor reports the ones whose branch is gone.
• User asks about the redesigned TUI: PTY overlays (l/L lazygit, r/R review, o/O shell, #35), the Settings panel (4) and its live-editable Keys tab (#294), the Command Logs modal (3), the Working Tree file-explorer pane (#300), the current-PR CI indicator (#299), [tui.keys.modal.<context>] rebindable overlay keys (#219), and [tui.macro1]/[tui.macro2] (h/H).
• User mentions .gwm.toml (per-repo config) or any of its sections: [worktree], [doctor], [tui], [tui.open], [git_tui], [review], [[bootstrap.copy]], [[bootstrap.guard]], [[bootstrap.no_symlink]], [[bootstrap.command]], [bootstrap.fallback.*].
• User asks about composable when predicates (file_exists:, cmd_exists:, env_set:, env_eq:, glob_exists:) and the ! / && / || operators.
• User wants to migrate a tools/worktree-manager.sh or gwq-based workflow to gwm.
• User asks how to set up the AWS RDS guard, the safe .env.testing fallback, or the no-symlink invariant for vendor/ / node_modules/.
• User asks about the branch convention <type>/#<issue>-<desc> or its overrides.
• User wants to link a worktree to a GitHub issue / PR, refresh GitHub status from inside the TUI, or run gwm doctor to validate setup before pushing.
• User mentions gcd <pattern> (shell wrapper from gwm shell-init <shell>).
• User wants tmux / zellij hand-off (gwm tmux <pat>, gwm zellij <pat> with optional --split).
• User wants to configure the TUI l (git_tui) / R (review) launchers, the o (open dispatch: shell/editor/finder), or y (yank path to clipboard) k