Skip to content
workmux branch logoworkmux branch logoworkmux

list

Copy page

Lists git worktrees with their agent status, multiplexer window status, and merge status. Alias: ls

Terminal window
workmux list [options] [worktree-or-branch...]

Arguments

Section titled “Arguments”
Argument Description
worktree-or-branch Filter by worktree handle (directory name) or branch name. Multiple values supported. Optional.

Options

Section titled “Options”
Flag Description
--all Include worktrees from every repository represented by a tracked agent in the current multiplexer instance. Repositories without tracked agents cannot be discovered.
--pr Show GitHub PR status for each worktree. Requires the gh CLI to be installed and authenticated. Note that it shows pull requests’ statuses with Nerd Font icons, which requires Nerd Font compatible font installed.
--json Output as JSON. Produces a JSON array with project, project_path, handle, branch, path, is_main, mode, has_uncommitted_changes, is_open, agent_statuses, and created_at.

Examples

Section titled “Examples”
Terminal window
# List all worktrees
workmux list


# List with PR status
workmux list --pr


# Output tracked projects as one JSON response
workmux list --all --json


# Filter to a specific worktree
workmux list my-feature


# Filter to multiple worktrees
workmux list feature-auth feature-api

Example output

Section titled “Example output”
BRANCH      AGE  AGENT  MUX  UNMERGED  PATH
main        -    -      -    -         ~/project
user-auth   2h   🤖     ✓    -         ~/project__worktrees/user-auth
bug-fix     3d   ✅     ✓    ●         ~/project__worktrees/bug-fix
api-work    1w   -      ✓    -         ~/project__worktrees/api-work

Key

Section titled “Key”
  • AGE column shows how old the worktree is, based on directory creation time. Uses compact units: m, h, d, w, mo, y. Shows - for the main worktree or when creation time is unavailable.
  • AGENT column shows the current agent status using status icons:
    • 🤖 = agent is working
    • 💬 = agent is waiting for user input
    • ✅ = agent finished
    • When multiple agents run in one worktree, shows a count (e.g., 2🤖 1✅)
    • When stdout is piped (e.g., by a script or agent), text labels are used instead: working, waiting, done
  • ✓ in MUX column = multiplexer window exists for this worktree
  • ● in UNMERGED column = branch has commits not merged into main
  • - = not applicable