checkout — Claude Code command: create and switch git branches
The checkout command creates and switches git branches using prefixes such as feature/, hotfix/ and release/, following a repo's branch-naming convention.
MIT ★ 763 updated 2026-03-31
.claude/commands/checkout.mdWhat checkout does
Give it an argument and it works out the branch. A name with a slash is read as type/name. A bare word makes it ask for a type, or offer feature/. Before that it prints the current branch and up to 20 branches that already exist.
Then the checks: is the branch local or on the remote, does the name run past 50 characters. A local branch gets a plain git checkout, a remote-only one is created with -b against origin/, and a new one is a fresh -b. The starting point follows the prefix: hotfix/ from main or master, feature/ from develop when it exists, release/ from develop or main.
Uncommitted work stays where it is. A dirty tree earns a warning and a nudge to stash or commit, not a silent switch. Spaces become hyphens, capitals drop, stray characters are stripped. At the end you see upstream tracking and a pointer to /git:push.
What it helps with
- start a
feature/branch named the way the repo expects - jump to an existing branch without scanning
git branch -ayourself - cut a
hotfix/straight from main - pull a remote-only branch down with origin tracking
- turn a messy branch name into something git accepts
Example prompts for the agent
- Run
/git:checkout feature/user-authenticationand switch me onto it. - Cut
hotfix/security-patchfrom main. - Move me to
develop.
How to install checkout
Manually: put the files in place
.claude/commands/checkout.mdCall it with /checkout. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/checkout.mdCall it with /prompts:checkout. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/checkout.prompt.mdManually: put the files in place
.gemini/commands/checkout.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about checkout
How do I install checkout in Claude Code?
Put checkout.md at .claude/commands/checkout.md inside your project. The command then runs as /git:checkout.
What does checkout do?
It creates or switches a git branch from a type/name argument. Along the way it checks whether the branch exists locally or on the remote and picks a base branch from the prefix.
What happens with uncommitted changes?
You get a warning about the dirty working directory and a suggestion to stash or commit. The command does not hide the changes itself.
Source text
checkout.md · MIT
--- description: Smart branch creation and switching with conventional naming allowed-tools: Bash(git:*), Read category: workflow argument-hint: "<branch-type/branch-name | branch-name>" --- # Git Checkout: Smart Branch Management Create or switch to branches with intelligent naming conventions and setup. ## Current Branch Status !`git branch --show-current 2>/dev/null || echo "(no branch)"` ## Available Branches !`git branch -a 2>/dev/null | head -20` ## Branch Creation Task Based on the arguments provided: `$ARGUMENTS` Parse the branch specification and create/switch to the appropriate branch. ### Supported Branch Types - `feature/` - New features and enhancements - `bugfix/` - Bug fixes (non-critical) - `hotfix/` - Urgent production fixes - `release/` - Release preparation branches - `chore/` - Maintenance and cleanup tasks - `experiment/` - Experimental features - `docs/` - Documentation updates - `test/` - Test-related changes - `refactor/` - Code refactoring ### Branch Naming Rules 1. If argument contains `/`, use as-is (e.g., `feature/user-auth`) 2. If argument is single word, suggest adding a prefix 3. Convert spaces to hyphens 4. Lowercase all characters 5. Remove special characters except hyphens and slashes 6. Validate branch name is git-compatible ### Workflow 1. **Parse the branch argument**: - If empty, show current branch and available branches - If contains `/`, treat as type/name format - If single word without `/`, ask for branch type or suggest `feature/` 2. **Validate branch name**: - Check if branch already exists locally - Check if branch exists on remote - Ensure name follows git conventions - Warn if name is too long (>50 chars) 3. **Create or switch branch**: - If branch exists locally: `git checkout <branch>` - If branch exists only on remote: `git checkout -b <branch> origin/<branch>` - If new branch: `git checkout -b <branch>` 4. **Set up branch configuration**: - For hotfix branches: Base off main/master - For feature branches: Base off current branch or develop - For release branches: Base off develop or main 5. **Report status**: - Confirm branch switch/creation - Show upstream tracking status - Suggest next steps (e.g., "Ready to start working. Use /git:push to set upstream when ready to push.") ### Examples ```bash # Create feature branch /git:checkout feature/user-authentication # Create hotfix from main /git:checkout hotfix/security-patch # Switch to existing branch /git:checkout develop # Create branch without prefix (will prompt) /git:checkout payment-integration ``` ### Special Handling For hotfix branches: - Automatically checkout from main/master first - Set high priority indicator - Suggest immediate push after fix For feature branches: - Check if develop branch exists, use as base - Otherwise use current branch as base For release branches: - Validate version format if provided (e.g., release/v1.2.0) - Set up from develop or main ### Error Handling - If branch name is invalid, suggest corrections - If checkout fails, show git error and provide guidance - If working directory is dirty, warn and suggest stashing or committing
© carlrannaberg · MIT · carlrannaberg/claudekit