Workie

A developer CLI for Git worktree management.

Install

go install github.com/agoodway/workie@latest

Or build from source:

git clone https://github.com/agoodway/workie.git
cd workie
go build -o workie .

Requires Go 1.22+.

Commands

workie begin [branch-name]

Create a new worktree for isolated development.

workie begin feature/new-ui

Creates a worktree under <repo>-worktrees/<branch>/, copies configured files, and runs post_create hooks.

workie finish [branch-name]

Remove a worktree.

workie finish feature/old-branch
workie finish feature/old-branch --prune-branch   # also delete the branch
workie finish feature/old-branch --force           # skip uncommitted changes check

workie setup [branch-name]

Copy configured files and run post_create hooks on an existing worktree. Does not run git worktree add or create a branch. Use this when another tool (for example Codex) already created the worktree.

This is different from workie setup-sprite, which configures sprite.dev VMs.

workie setup feature/foo --source-tree-path /repo --worktree-path /path/to/worktree
workie setup --source-tree-path /repo --worktree-path /path/to/worktree   # branch from checked-out branch

Flags / env:

Input	Description
--source-tree-path	Source git repository (falls back to CODEX_SOURCE_TREE_PATH)
--worktree-path	Existing worktree directory (falls back to CODEX_WORKTREE_PATH)

If no branch name is given, it is derived from the worktree's checked-out branch (detached HEAD is rejected). If given, [branch-name] must match that branch.

workie cleanup [branch-name]

Run pre_remove hooks and a dirty-worktree check on an existing worktree. Does not run git worktree remove or delete branches.

workie cleanup feature/foo --source-tree-path /repo --worktree-path /path/to/worktree
workie cleanup feature/foo --source-tree-path /repo --worktree-path /path/to/worktree --force

Flags / env:

Input	Description
--source-tree-path	Source git repository (falls back to CODEX_SOURCE_TREE_PATH)
--worktree-path	Existing worktree directory (falls back to CODEX_WORKTREE_PATH)
--force	Skip the uncommitted-changes check only (does not remove the worktree)

If no branch name is given, it is derived from the worktree's checked-out branch (detached HEAD is rejected). If given, [branch-name] must match that branch.

workie setup-sprite

Run setup commands on sprite.dev VMs.

workie setup-sprite
workie setup-sprite --sprite my-vm --org my-org

workie init

Generate a .workie.yaml configuration file with commented examples.

workie init
workie init --force              # overwrite existing
workie init --output custom.yaml # custom filename

Root flags

workie --list       # list worktrees
workie --version    # version info
workie --config f   # custom config path
workie --verbose    # verbose output
workie --quiet      # quiet mode

Configuration

Place .workie.yaml in your repository root. Run workie init to generate a starter config.

# Files/directories to copy into new worktrees
files_to_copy:
  - .env.example
  - scripts/
  - config/development.yaml

# Lifecycle hooks
hooks:
  post_create:
    - "npm install"
    - "make setup"
  pre_remove:
    - "npm run cleanup"
  timeout_minutes: 5

# Sprite VM setup
sprite:
  name: "my-dev-vm"
  org: "my-org"
  pre_setup:
    - "mkdir -p ~/go/bin"
  post_setup:
    - "which td && td --version"

How it works

1. Detects the repository root via git rev-parse --show-toplevel
2. Loads .workie.yaml from the repo root
3. Creates worktrees under <repo>-worktrees/
4. Copies configured files into the new worktree
5. Runs lifecycle hooks (post_create / pre_remove)

License

MIT - see LICENSE.