sir

Opinionated & intelligent workspace management cli for parallel coding agents, wraps git worktrees.

What It Does

• Creates isolated workspaces under repo/.worktrees/<name>/
• Delegates initialization to Claude CLI (copies untracked .env files, target/, node_modules, etc.)
• Automatically intelligent merges changes from workspaces onto the repo root using the Claude CLI
• Runs agent commands directly in your current terminal

Requirements

• git
• Claude Code CLI (claude)

Install

Clone, then install globally:

cargo install --path .

Opiononated Workflow

1. Decide to build a new feature, add tests, etc. e.g. fix cargo test
2. sir n codex "fix cargo test" - auto generates a workspace name and opens the codex tui with my prompt
3. Follow-ups in codex and testing in terminal or review in Cursor
4. sir settle in workspace directory to intelligently settle back to main with auto-generated clean commits
5. Repeat & parallelize!

Read the whole README, there are useful tips!

Configuration

Config file lookup order:

1. ~/.config/sir/config.toml
2. ~/.sir.toml

Defaults:

claude_bin = "claude"
claude_model = "sonnet"

Example:

claude_bin = "claude"
claude_model = "sonnet"

Commands

sir doctor

Runs sanity checks and prints explicit remediation commands.

Checks include:

• inside a git repo
• .worktrees/ exists (creates it if missing)
• .worktrees/ is gitignored
• git worktree support (git worktree list)
• Claude CLI installed

sir new [--name/-n <name>] [--from <revision>] <agent_cmd...> (alias: sir n)

Creates/opens a workspace and then runs your agent command in that workspace in the current terminal.

Behavior:

• Ensures .worktrees/
• Uses automatic naming by default:
  • sends your full <agent_cmd...> to Claude and asks for a short workspace name
  • if Claude returns null (or invalid output), falls back to a generated two-word name (for example: pink elephant)
• Use --name / -n when you want an explicit workspace name
• Creates new worktrees from HEAD by default
  • use --from <revision> to choose a different base revision
• Creates a worktree branch under sir/*:
  • derived from the workspace name (whitespace collapsed to - for branch safety)
  • if branch exists: git worktree add repo/.worktrees/<name> <branch>
  • else: git worktree add -b <branch> repo/.worktrees/<name> <revision>
  • note: if branch already exists, --from is ignored
• Newly created worktrees are seeded with current uncommitted changes from the source repo by default
  • applies tracked staged/unstaged diff from HEAD
  • copies untracked files (excluding ignored files)
  • if workspace already exists, seeding is skipped
• If an existing workspace looks incomplete or not git-backed, sir auto-recreates it before running the agent command
• Runs Claude init prompt from repo root to copy:
  • .env (if present, non-destructive)
  • target/ (if present)
  • node_modules/ (if present)
  • no symlinks
  • uses --model sonnet by default (configurable via claude_model)
• Runs <agent_cmd...> through your $SHELL with cwd set to the workspace
• After the agent command exits, leaves you in an interactive $SHELL in that workspace

Examples:

sir new claude -p "fix flaky indexing test"
sir n codex
sir new --name feature-a claude -p "fix failing tests"
sir n -n bugfix-42 codex
sir new --from main codex

sir status [--json] (alias: sir t)

Workspace listing from .worktrees/ (excluding _logs, _tmp) plus any other linked git worktrees for this repo (for example Codex-managed external worktrees).

For each workspace, prints:

• short index (IDX) for fast targeting
• name
• backend detection (git or unknown)
• source (local or linked)
• status summary (git status -sb)

Examples:

sir status
sir t --json

sir open <name>

Opens an interactive shell in workspace <name>.

In non-interactive environments, it prints the workspace path instead of launching a shell.

Example:

sir open foo

sir rm [<name-or-index>] [--all-clean]

Removes workspace by <name-or-index>, or removes all clean workspaces with --all-clean.

Behavior:

• sir rm <name-or-index>:
  • resolves target from sir status rows (local + linked external worktrees)
  • supports either workspace name or IDX
  • removes git-backed workspaces with git worktree remove --force
  • if the workspace is non-git leftovers, deletes the directory directly
• sir rm --all-clean:
  • scans all discovered workspaces from sir status (local + linked)
  • for git-backed workspaces, checks git status --porcelain
  • removes only workspaces with no unstaged/untracked changes
  • skips dirty workspaces (including untracked files)
  • staged-only changes are treated as clean for this check

Example:

sir rm foo
sir rm 2
sir rm --all-clean

sir settle [<name>] [--prompt <text>] (alias: sir s)

Delegates integration of a workspace back to main to Claude.

Behavior:

• Workspace resolution:
  • provided name: repo/.worktrees/<name>
  • omitted name: inferred from current directory when inside a linked git worktree (.worktrees/<name> or an external worktree path such as Codex-managed worktrees)
• Runs Claude in workspace with --dangerously-skip-permissions
• Uses --model sonnet by default (configurable via claude_model)
• Appends --prompt <text> (or an inferred additional prompt) to the settle instructions
  • convenience behavior: when run inside a workspace, sir settle "extra instruction" treats the argument as additional prompt if it is not an existing workspace name
• Prompt instructs Claude to:
  • inspect status/diff/log with git
  • produce clean commit(s) and strong commit messages
  • integrate/rebase/merge onto latest main
  • resolve conflicts
  • not remove/prune the workspace worktree during settle
  • update .env when example env files changed (without overwriting secrets)
• After Claude returns, prints post-check:
  • git status -sb at repo root
• If sir settle is run while your current directory is inside a linked worktree, it opens an interactive shell at the repo root after settle completes

Examples:

sir settle foo
cd .worktrees/foo && sir settle
sir settle foo --prompt "run full test suite before final integration"
cd .worktrees/foo && sir settle "run full test suite before final integration"
# also works from external linked worktrees (example path shape):
cd ~/.codex/worktrees/3ed7/sir && sir settle

Notes

• Workspace names cannot contain path separators and cannot be _logs or _tmp.
• sir is git-only.

Development

Using just:

just build
just test
just clippy
just fmt
just run -- --help