gwt — git worktree + agent, one command

gwt creates a git worktree, clones submodules at their latest branch HEAD, then launches your coding agent — all in one command. No agent config needed: it auto-detects what's on your machine.

gwt my-feature           # worktree + auto-detected agent (pi > codex > …)
gwt -w claude fix-bug    # worktree + specific agent
gwt --no-agent scratch   # worktree only

---

Why

git worktree add is great, but git submodule update --init afterwards breaks when the pinned SHA was garbage-collected or force-pushed.

gwt clones each submodule directly from its branch HEAD — never stale. And since you're going to open a coding session anyway, it launches the agent too. Just gwt fix-login and you're coding.

---

Install

Zero sudo. Clone and add two lines to your shell rc.

git clone https://github.com/4ier/gwt.git ~/code/gwt

Then in ~/.zshrc (or ~/.bashrc):

export PATH="$HOME/code/gwt:$PATH"    # gwt, gwt-doctor on PATH
source ~/code/gwt/init.sh             # gwt() wrapper function

Optional:

export GWT_WITH=pi                    # override auto-detect
export GWT_SUB_BRANCH=develop         # default submodule branch

---

Agent resolution

gwt picks your agent in this order:

Priority	Source	Example
1. -w flag	Explicit	gwt -w codex feat
2. GWT_WITH env	Persistent default	export GWT_WITH=claude
3. Auto-detect	First on PATH	pi → codex → claude → gemini → agent → …
4. Fallback	No agent found	Plain worktree, prints path

Aliases work anywhere in the chain because the wrapper uses eval exec:

alias claude-a='claude --dangerously-skip-permissions'
gwt -w claude-a fix         # alias expands fine

---

Usage

# Default: worktree + auto-detect agent
gwt my-feature                # → creates worktree, launches pi (if installed)

# Pick an agent
gwt -w claude fix-bug         # → worktree + claude
gwt -w codex experiment       # → worktree + codex

# Worktree only
gwt --no-agent scratch        # → prints path, no agent launched

# Custom base branch
gwt -b develop hotfix         # → from develop, not main

# Sync before work
gwt --sync my-feature          # → pull latest, update submodule pointers, then agent

# Preview
gwt --dry-run test

---

How it works

gwt (shell function)  →  gwt.sh (bash subprocess)  →  git worktree + submodules
     │                          │
     └─ resolve agent           └─ porcelain output (stdout = path)
        eval exec $agent

• gwt.sh — the engine. Creates worktree, handles submodules. stdout = path.
• init.sh — the wrapper. source it to get the gwt() function. Agent resolution, then eval exec.
• doctor.sh — self-check. Shows what agents are available and which one gwt will pick.

---

Submodule behaviour

Scenario	Behaviour
Plain repo (no .gitmodules)	Simple git worktree add
Repo with submodules	Worktree + each submodule cloned from branch HEAD
Branch fallback per submodule	.gitmodules annotation → main → remote HEAD

---

Doctor

gwt-doctor

Checks: bash, zsh, git, worktree support, PATH, agent auto-detection, SSH.

---

Design

1. Default agent-first. gwt fix-login does everything — you're coding immediately.
2. Zero config. No agent installed? Detects it and falls back to plain worktree.
3. Pure engine. gwt.sh does one job: create a worktree. One output: a path.
4. Thin wrapper. init.sh is ~40 lines. Agent resolution, cd, eval exec.
5. No sudo. Add the repo directory to $PATH.
6. No project coupling. Reads .gitmodules — works with any git repo.
7. Cross-platform. bash 3.2+ / zsh 5+. macOS, Linux.

---

Naming

gwt = git worktree. Three letters, says exactly what it does.

Originally named ame (anemone / 海葵, from Finding Nemo) because each worktree is a safe place to grow code.

---

License

MIT