codex-git-branch-hook

Archived

This project is archived.

Codex now supports Git branch display in the native TUI status line, so a hook project is not needed for the original goal. Use Codex's built-in configuration instead:

[tui]
status_line = ["model-with-reasoning", "current-dir", "git-branch"]

Restart Codex after editing ~/.codex/config.toml.

This repository remains available only as historical reference for the earlier hook and installer experiment. New installs are not recommended.

Historical Context

This project started as a minimal Codex CLI hook that printed the current Git branch when a Codex session started. It later added a helper installer for Codex's native git-branch TUI status-line item, but that native support makes the project unnecessary for persistent footer branch display.

The Homebrew Nerd Font dependency was only useful for this project's own hook output, not for Codex's native persistent footer. Codex controls the native footer renderer and currently displays the branch as plain text.

Previous README

What you get

Persistent Codex TUI footer branch display:

gpt-5.5 medium · ~/Projects/candidateos · feature/public-profile-page

Codex startup reminder from any working directory:

🌿 Codex Git Branch Hook

Repository:
~/projects/candidateos

Branch:
 feature/public-profile-page

Reminder:
Verify you are working on the expected branch before editing files.

See examples/example-output.md.

How it works

Codex hooks are lifecycle commands that Codex runs during events such as session start, prompt submission, tool use, and stop.

The global installer updates ~/.codex/config.toml by:

• enabling hooks with [features].hooks = true
• adding git-branch to [tui].status_line
• adding a managed SessionStart hook block
• calling the Homebrew-installed executable by absolute path
• backing up existing config before modifying it
• preserving unrelated Codex settings

Codex's built-in TUI status line reads [tui].status_line from config.toml. The installer preserves existing status-line items and appends git-branch when it is missing.

For SessionStart, Codex adds plain stdout as extra developer context, so the branch reminder appears at startup. The hook matcher is startup|resume|clear.

Recommended Install

brew tap pixxelboy/brew-tap https://github.com/pixxelboy/brew-tap.git
brew install pixxelboy/brew-tap/codex-gitbranch-hook
codex-gitbranch-hook install --global

Homebrew installs the required Nerd Font cask automatically:

font-meslo-lg-nerd-font

Then verify:

codex-gitbranch-hook doctor
codex-gitbranch-hook preview

Start or restart Codex from any folder. The first time Codex sees this hook, it may show:

1 hook needs review before it can run. Open /hooks to review it.

Open /hooks in Codex, review the command, and approve it. This is expected Codex safety behavior for project hooks.

Commands

Print the same output Codex will receive:

codex-gitbranch-hook
codex-gitbranch-hook preview

Register globally:

codex-gitbranch-hook install --global

Remove the global registration:

codex-gitbranch-hook uninstall --global

Inspect the setup:

codex-gitbranch-hook doctor

The legacy executable name is also installed for compatibility:

codex-git-branch-hook preview

Branch Icon

The default branch icon is the Nerd Font Git branch glyph:



Homebrew installs the required font automatically. You may still need to select it in your terminal settings. Recommended terminal font:

MesloLGS NF

Terminal font selection examples:

• Terminal.app: Settings -> Profiles -> Text -> Font
• iTerm2: Settings -> Profiles -> Text -> Font
• Warp: Settings -> Appearance -> Text -> Terminal font
• VS Code terminal: set terminal.integrated.fontFamily to MesloLGS NF

Fallback icon modes are available through CODEX_GITBRANCH_ICON:

CODEX_GITBRANCH_ICON=emoji codex-gitbranch-hook preview
CODEX_GITBRANCH_ICON=text codex-gitbranch-hook preview
CODEX_GITBRANCH_ICON=none codex-gitbranch-hook preview

Global vs Project Install

Global install is recommended because it works everywhere Codex runs. It modifies only the user-level Codex config:

~/.codex/config.toml

Project-local install is still available for repositories that should carry their own .codex/ files:

codex-gitbranch-hook install /path/to/your/repo
codex-gitbranch-hook uninstall /path/to/your/repo
codex-gitbranch-hook status /path/to/your/repo

Project-local hooks load only when that project .codex/ layer is trusted. Global hooks load from the user config layer.

Homebrew

The Homebrew tap is published at pixxelboy/brew-tap.

Tap it and install the formula:

brew tap pixxelboy/brew-tap https://github.com/pixxelboy/brew-tap.git
brew install pixxelboy/brew-tap/codex-gitbranch-hook
codex-gitbranch-hook install --global

The formula depends on font-meslo-lg-nerd-font, so Homebrew installs the required Nerd Font with the CLI. Terminal font selection remains a user preference and is not changed automatically.

To install the latest main branch instead of the tagged release:

brew install --HEAD pixxelboy/brew-tap/codex-gitbranch-hook

Because the tap repository is named brew-tap, use the explicit URL form above. The shorter Homebrew command below would require a repository named pixxelboy/homebrew-tap:

brew tap pixxelboy/tap

Unregister from Codex:

codex-gitbranch-hook uninstall --global

Remove the Homebrew package:

brew uninstall codex-gitbranch-hook

If brew tap pixxelboy/tap asks for a GitHub username, use the explicit URL form:

brew tap pixxelboy/brew-tap https://github.com/pixxelboy/brew-tap.git

Local testing

Run the test suite:

test/run-tests.sh

Run ShellCheck:

shellcheck bin/codex-gitbranch-hook bin/codex-git-branch-hook test/run-tests.sh .codex/hooks/git-branch-session-start.sh

Preview output:

bin/codex-gitbranch-hook preview

Test outside Git:

tmpdir="$(mktemp -d)"
cd "$tmpdir"
codex-gitbranch-hook preview

Behavior

The hook detects:

• Git repository root
• Current branch
• Detached HEAD state
• Missing git
• Non-Git folders

Detached HEAD output looks like:

Branch:
detached HEAD (abc1234)

In a non-Git folder, it exits successfully and reports:

Branch:
Not a Git repository.

If git is missing from PATH, it exits successfully and reports that Git is unavailable.

Troubleshooting

If codex-gitbranch-hook is not found after Homebrew install:

• On Apple Silicon, make sure /opt/homebrew/bin is on PATH.
• On Intel macOS, make sure /usr/local/bin is on PATH.
• Open a new terminal after installing with Homebrew.
• Run brew --prefix to confirm your Homebrew prefix.

If the branch icon shows as a box or odd symbol:

• Confirm Homebrew installed font-meslo-lg-nerd-font.
• Select MesloLGS NF as your terminal font.
• Run codex-gitbranch-hook doctor and check the glyph preview.
• The font is installed, but your terminal may not be using it yet.
• Use CODEX_GITBRANCH_ICON=emoji, text, or none if you prefer a fallback.

If nothing appears at session startup:

• Run codex-gitbranch-hook doctor.
• Confirm ~/.codex/config.toml contains [features].hooks = true.
• If Codex says a hook needs review, open /hooks in Codex and approve the hook.
• Restart Codex after running codex-gitbranch-hook install --global.

If the branch is missing from the bottom Codex pane:

• Run codex-gitbranch-hook install --global again; it is idempotent.
• Confirm ~/.codex/config.toml contains [tui] with status_line including "git-branch".
• Restart Codex after changing ~/.codex/config.toml.
• Run codex-gitbranch-hook doctor and check TUI status line.

If global uninstall cannot find a managed block, the tool leaves your config untouched. Remove custom hook entries manually only if you added them yourself.

Compatibility

• macOS and Linux
• Bash
• Git repositories using normal branches or detached HEAD
• Current Codex hook system with SessionStart

Windows is not targeted by this project because the hook script is Bash-based.

Limitations

• This project is informational only. It does not prevent edits on the wrong branch.
• It does not inspect remote tracking state, dirty worktrees, or pull request metadata.
• The global installer manages its marked hook block and adds git-branch to Codex's TUI status_line.
• The tool does not approve Codex hooks for you; review remains a Codex safety step.
• The tool does not modify Terminal.app, iTerm2, Warp, Ghostty, VS Code, or shell profile settings.
• Codex status-line and hook behavior can change while the feature evolves; check the official docs when upgrading Codex.

Official references

• Codex hooks documentation
• Codex config basics
• OpenAI Codex CLI repository

License

MIT. See LICENSE.