How to Configure Ponytail for a Statusline Badge in Claude Code

To configure Ponytail for a statusline badge in Claude Code, add a statusLine command entry to ~/.claude/settings.json that runs the appropriate badge script (ponytail-statusline.sh on Unix or ponytail-statusline.ps1 on Windows).

The Ponytail plugin for Claude Code adds a visual indicator to your statusline showing the current Ponytail mode (e.g., [PONYTAIL] or [PONYTAIL:ULTRA]). According to the DietrichGebert/ponytail source code, this badge integrates with Claude's native statusLine configuration to display real-time state without interfering with your existing setup.

How the Ponytail Statusline Badge Works

The badge system relies on a flag file written to $CLAUDE_CONFIG_DIR/.ponytail-active during session initialization. A lightweight shell or PowerShell script reads this flag and outputs a short string that Claude renders in the top-right corner of the interface.

The configuration requires a JSON object in ~/.claude/settings.json with this structure:

{
  "statusLine": {
    "type": "command",
    "command": "<shell-command-that-runs-the-badge-script>"
  }
}

Automatic Configuration via Session Hooks

Ponytail can configure the statusline automatically through its activation hook, or you can set it up manually.

Session Start Hook (hooks/ponytail-activate.js)

The hooks/ponytail-activate.js file runs on every Claude session start (see lines 44-76). This script performs three critical tasks:

• Writes the flag file to indicate Ponytail is active
• Emits the Ponytail ruleset to Claude
• Detects whether a statusLine entry already exists in ~/.claude/settings.json

If no statusLine configuration exists, the hook emits a setup nudge containing the exact JSON snippet needed for your platform.

The Nudge Mechanism

When you first start a Claude session after installing Ponytail, the hook checks for a hidden flag file (.ponytail-statusline-nudged) to ensure the prompt appears only once. If absent, it outputs a message like:

STATUSLINE SETUP NEEDED: The ponytail plugin includes a statusline badge showing active mode [...]
To enable, add this to /home/you/.claude/settings.json:
"statusLine": { "type": "command", "command": "bash \"/home/you/git/ponytail/hooks/ponytail-statusline.sh\"" }

Copy this JSON snippet into your settings file and restart Claude. The badge will immediately display your current Ponytail mode.

Manual Configuration Steps

If you prefer to configure the badge manually or missed the automatic nudge, follow these platform-specific instructions.

Unix and macOS Configuration

Add the following to ~/.claude/settings.json, replacing <PATH_TO_REPO> with the absolute path to your Ponytail installation:

{
  "statusLine": {
    "type": "command",
    "command": "bash \"<PATH_TO_REPO>/hooks/ponytail-statusline.sh\""
  }
}

For example, if you cloned Ponytail to ~/git/ponytail, the command would be:

{
  "statusLine": {
    "type": "command",
    "command": "bash \"~/git/ponytail/hooks/ponytail-statusline.sh\""
  }
}

Windows PowerShell Configuration

On Windows, use the PowerShell script with bypass execution policy:

{
  "statusLine": {
    "type": "command",
    "command": "powershell -ExecutionPolicy Bypass -File \"<PATH_TO_REPO>\\hooks\\ponytail-statusline.ps1\""
  }
}

Note: The path separators must be escaped backslashes (\\) within the JSON string.

Cross-Platform Badge Scripts

Ponytail provides separate scripts for Unix and Windows to ensure compatibility without external dependencies.

• hooks/ponytail-statusline.sh: Reads $CLAUDE_CONFIG_DIR/.ponytail-active and prints the mode badge for macOS and Linux systems.
• hooks/ponytail-statusline.ps1: performs the identical function for Windows environments.

Both scripts are deliberately minimal to ensure fast execution on every statusline refresh. The hooks/ponytail-activate.js script validates paths using an isShellSafe() check before suggesting them, preventing shell-injection vulnerabilities from malformed installation paths.

Removing the Statusline Badge

To remove Ponytail completely while preserving your own custom statusline configurations, run:

node scripts/uninstall.js

The scripts/uninstall.js file (around line 30) deletes the flag file, removes the Ponytail configuration entry, and only removes the statusLine entry if it points specifically at Ponytail's own script. Any user-defined statusLine settings remain untouched, ensuring the uninstaller is non-destructive to your existing Claude Code setup.

Summary

• Configuration location: Add the statusLine JSON object to ~/.claude/settings.json.
• Unix command: Use bash to execute hooks/ponytail-statusline.sh with the absolute repository path.
• Windows command: Use powershell with -ExecutionPolicy Bypass to run hooks/ponytail-statusline.ps1.
• Automatic setup: The hooks/ponytail-activate.js script offers a one-time nudge with the correct JSON snippet if no statusline exists.
• Safety features: The hook validates shell safety before inserting paths and uses flag files to prevent duplicate prompts.
• Clean removal: scripts/uninstall.js removes only Ponytail-specific entries, preserving your custom statusline settings.

Frequently Asked Questions

How do I know if the statusline badge is working correctly?

Once configured, the badge appears in the top-right corner of Claude Code displaying [PONYTAIL] or [PONYTAIL:ULTRA]. If you see this text, the hooks/ponytail-statusline.sh (or .ps1) script is successfully reading the flag file written by hooks/ponytail-activate.js. If the badge is absent, verify that ~/.claude/settings.json contains valid JSON and that the script path points to your actual Ponytail installation directory.

Can I use Ponytail with my own custom statusline configuration?

Yes. Ponytail explicitly checks for existing statusLine entries in hooks/ponytail-activate.js before suggesting its badge. If you already have a custom statusline, the hook will not overwrite it or show the setup nudge. Additionally, scripts/uninstall.js only removes the statusline entry if it specifically references Ponytail's badge script, leaving your custom configurations intact.

What file does Ponytail use to track active sessions?

Ponytail writes a flag file to $CLAUDE_CONFIG_DIR/.ponytail-active when the session starts. The badge scripts (ponytail-statusline.sh and ponytail-statusline.ps1) read this file to determine what text to display. When you uninstall Ponytail, scripts/uninstall.js removes this flag file along with the configuration entries.

Is it safe to run the PowerShell script with ExecutionPolicy Bypass?

The hooks/ponytail-statusline.ps1 script is a read-only operation that simply outputs text based on the presence of the flag file. The -ExecutionPolicy Bypass flag is required because the script runs unsigned. However, you should always verify that the script content matches the official DietrichGebert/ponytail repository source code before execution, as this parameter does bypass standard security policies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}