# How to Configure Ponytail for a Statusline Badge in Claude Code

> Learn how to configure Ponytail for a statusline badge in Claude Code. Follow our guide to add a statusLine command to your settings.json for clear visual feedback.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: how-to-guide
- Published: 2026-09-09

---

**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`](https://github.com/DietrichGebert/ponytail/blob/main/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](https://github.com/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:

```json
{
  "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`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```json
{
  "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:

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

```

### Windows PowerShell Configuration

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

```json
{
  "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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```bash
node scripts/uninstall.js

```

The [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-statusline.sh) (or `.ps1`) script is successfully reading the flag file written by [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-statusline.sh) and `ponytail-statusline.ps1`) read this file to determine what text to display. When you uninstall Ponytail, [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/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](https://github.com/DietrichGebert/ponytail) repository source code before execution, as this parameter does bypass standard security policies.