How to Display Git Branch and Status in Claude Code Statusline

Mar 21, 2026

When I’m deep in a Claude Code session, I constantly need to know my git state. Which branch am I on? Do I have uncommitted changes? Am I ahead or behind the remote?

Every time I switch to another terminal to run git status, I break my flow. I wanted this information right in front of me, without the context switch.

The Problem

I found myself running these commands repeatedly:

git branch --show-current
git status --porcelain
git rev-list --left-right --count @{upstream}...HEAD

This worked, but the mental overhead of switching contexts added up. I needed the git state visible at all times in my Claude Code statusline.

The Solution: Claude HUD

Claude HUD integrates git status directly into the statusline. Once configured, I see my repository state without running any commands.

The display options range from minimal to detailed:

Branch only:     git:(main)
Branch + dirty:  git:(main*)
Full details:    git:(main* ↑2 ↓1)
File stats:      git:(main* !3 +1 ?2)

How It Works

Claude HUD extracts git information using standard git commands:

Branch name: git rev-parse --abbrev-ref HEAD
Dirty state: git status --porcelain (any output means dirty)
Ahead/behind: git rev-list --left-right --count @{upstream}...HEAD
File stats: Parsed from porcelain output

The result is a structured status object:

interface GitStatus {
  branch: string;
  isDirty: boolean;
  ahead: number;
  behind: number;
  fileStats?: FileStats;
}

Understanding the Display

Branch and Dirty State

The * symbol indicates uncommitted changes:

git:(main)   # Clean working tree
git:(main*)  # Uncommitted changes exist

Ahead/Behind Counts

When enabled, I see how many commits I’m ahead or behind the remote:

git:(main ↑2)    # 2 commits ahead of remote
git:(main ↓1)    # 1 commit behind remote
git:(main ↑2 ↓1) # 2 ahead, 1 behind

This tells me at a glance whether I need to pull or push.

File Statistics

The file stats mode shows change counts in Starship-compatible format:

git:(main* !3 +1 ?2)

!3 = 3 modified files
+1 = 1 added/staged file
?2 = 2 untracked files

The symbols:

! = modified
+ = added/staged
✘ = deleted
? = untracked

Configuration

I configure the git display in ~/.claude/plugins/claude-hud/config.json:

{
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": false
  }
}

Each option controls what appears:

Setting	Default	Effect
`enabled`	`true`	Show git branch at all
`showDirty`	`true`	Show `*` for uncommitted changes
`showAheadBehind`	`false`	Show `↑N ↓N` for sync status
`showFileStats`	`false`	Show file change counts

Choosing a Display Style

For minimal distraction, I use branch-only mode:

{
  "gitStatus": {
    "enabled": true,
    "showDirty": false,
    "showAheadBehind": false,
    "showFileStats": false
  }
}

For full awareness, I enable everything:

{
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  }
}

I can also run /claude-hud:configure to interactively select the style I want.

Why This Matters

Git context informs many decisions in a development workflow:

Before committing: I see if there are uncommitted changes
Before pushing: I know how many commits need pushing
Before creating a PR: I confirm I’m on the right branch
During collaboration: I spot if I’m behind the remote

Having this information in the statusline means I never need to break my Claude Code session to check git state.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Claude HUD GitHub

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!