# How `ponytail-statusline.sh` and `ponytail-statusline.ps1` Work: Cross-Platform Status Indicators for PONYTAIL

> Discover how ponytail-statusline.sh and .ps1 create cross-platform status indicators for PONYTAIL by reading state flags and emitting color-coded ANSI segments. Understand the core functionality.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: internals
- Published: 2026-09-11

---

**Both [`ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-statusline.sh) and `ponytail-statusline.ps1` are lightweight shell utilities that read a state flag from the Claude configuration directory and emit a color-coded ANSI segment indicating the active PONYTAIL mode.**

These scripts serve as the visual feedback mechanism for the **PONYTAIL** toolchain, enabling users to see at a glance whether the system is operating in `full`, `ultra`, `debug`, or other modes directly within their terminal prompt. Written for Bash and PowerShell respectively, they share identical logic for file detection, mode parsing, and colored output generation.

## Core Mechanics of the Status Scripts

The scripts operate through a four-stage pipeline: detecting the state file, extracting the mode string, selecting the appropriate color code, and printing a formatted ANSI escape sequence.

### Flag File Detection Logic

Both implementations first resolve the path to `.ponytail-active`, prioritizing the `CLAUDE_CONFIG_DIR` environment variable before falling back to the default `~/.claude` directory.

In **[`hooks/ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-statusline.sh)**, the path construction uses shell parameter expansion:

```bash
flag="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.ponytail-active"

```

The PowerShell implementation in **`hooks/ponytail-statusline.ps1`** uses `Join-Path` for cross-platform path compatibility:

```powershell
$ClaudeDir = if ($env:CLAUDE_CONFIG_DIR) { $env:CLAUDE_CONFIG_DIR } else { Join-Path $HOME ".claude" }
$Flag = Join-Path $ClaudeDir ".ponytail-active"

```

If the file does not exist, both scripts exit silently with code `0` to avoid polluting the prompt when PONYTAIL is inactive. The Bash version checks `[ -f "$flag" ] || exit 0`, while PowerShell uses `if (-not (Test-Path $Flag)) { exit 0 }`.

### Mode Parsing and Validation

When the flag file exists, the scripts read the first line to determine the operational mode. The Bash script strips whitespace using `tr`:

```bash
mode=$(head -n1 "$flag" | tr -d '[:space:]')

```

The PowerShell equivalent uses `Select-Object` and the `.Trim()` method:

```powershell
$Mode = (Get-Content $Flag -ErrorAction Stop | Select-Object -First 1).Trim()

```

This line encodes the PONYTAIL mode (e.g., `full`, `ultra`, `debug`), which determines both the color and the text format of the output segment.

### Color-Coded Output Generation

The scripts implement a two-color system using 256-color ANSI codes:

- **108** (green-ish): Default color for standard modes
- **173** (amber-ish): Reserved for `ultra` mode to provide high-visibility warning

In [`ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-statusline.sh), the color selection is handled via a conditional:

```bash
color=108
[ "$mode" = "ultra" ] && color=173

```

The PowerShell version uses a ternary-style `if` statement:

```powershell
$Color = if ($Mode -eq "ultra") { "173" } else { "108" }

```

The final output format varies by mode. When the mode is empty or `full`, the scripts output `[PONYTAIL]`. For any other mode, they output `[PONYTAIL:MODE]` with the mode text upper-cased. Both wrap the text in `\033[38;5;<color>m` ANSI sequences to apply the foreground color, resetting with `\033[0m`.

## Bash Implementation Details ([`ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-statusline.sh))

Located at [`hooks/ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-statusline.sh), the Bash implementation uses POSIX-compliant utilities for maximum compatibility. The script constructs the final output using `printf` with literal escape sequences:

```bash
printf '\033[38;5;%sm[PONYTAIL]\033[0m' "$color"

```

For non-full modes, it pipes the mode string through `tr '[:lower:]' '[:upper:]'` to ensure consistent capitalization before embedding it in the bracketed tag.

## PowerShell Implementation Details (`ponytail-statusline.ps1`)

The `hooks/ponytail-statusline.ps1` script uses `[char]27` (the ESC character) to build ANSI sequences compatible with modern Windows Terminal and PowerShell console hosts:

```powershell
$Esc = [char]27
[Console]::Write("${Esc}[38;5;${Color}m[PONYTAIL]${Esc}[0m")

```

When a specific mode suffix is required, the script constructs the string dynamically:

```powershell
[Console]::Write("${Esc}[38;5;${Color}m[PONYTAIL:$Suffix]${Esc}[0m")

```

Using `[Console]::Write` ensures the output bypasses PowerShell's default formatting and streams directly to the terminal.

## Integrating the Status Segments into Your Prompt

### Bash Configuration

Add the following to your `~/.bashrc` to execute the script and append the segment to your prompt:

```bash

# Source the statusline script

source /path/to/ponytail-statusline.sh

# Or capture output directly

export PS1="${PS1}\$(/path/to/ponytail-statusline.sh) "

```

### PowerShell Configuration

In your `Microsoft.PowerShell_profile.ps1`, dot-source the script and modify the `prompt` function:

```powershell

# Load the status segment logic

. C:\path\to\ponytail-statusline.ps1

function prompt {
    $existing = & $(Get-Command -Name prompt).ScriptBlock
    $segment = if ([string]::IsNullOrEmpty($Mode) -or $Mode -eq 'full') { 
        "[PONYTAIL]" 
    } else { 
        "[PONYTAIL:$($Mode.ToUpper())]" 
    }
    return "$existing $segment "
}

```

### Standalone Usage

Both scripts can be executed directly for use in tmux status bars, screen hardstatus lines, or other external status monitors:

```bash

# Unix-like systems

/path/to/ponytail-statusline.sh

# Windows

powershell -File C:\path\to\ponytail-statusline.ps1

```

## Summary

- **Both scripts** read from `.ponytail-active` in `$CLAUDE_CONFIG_DIR` (or `~/.claude`) to determine the PONYTAIL state.
- **Silent operation** is the default when no flag file exists, ensuring clean prompts when PONYTAIL is inactive.
- **Color coding** uses ANSI 256-color codes: **108** for standard modes and **173** for `ultra` mode.
- **Output format** adapts based on the mode: `[PONYTAIL]` for default/full modes, `[PONYTAIL:MODE]` for specific modes.
- **Cross-platform compatibility** is achieved through POSIX-compliant Bash and modern PowerShell with `[Console]::Write`.

## Frequently Asked Questions

### Where does the PONYTAIL status line script look for the state file?

According to the source code in [`hooks/ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-statusline.sh) and `hooks/ponytail-statusline.ps1`, the scripts check the `CLAUDE_CONFIG_DIR` environment variable first. If unset, they default to `$HOME/.claude` (Bash) or `Join-Path $HOME ".claude"` (PowerShell), looking for a file named `.ponytail-active`.

### Why does the status segment disappear when PONYTAIL is not active?

Both scripts are designed to exit with code `0` immediately if the `.ponytail-active` flag file is missing. This prevents `[PONYTAIL]` from appearing in your prompt when the toolchain is not engaged. The Bash script uses `[ -f "$flag" ] || exit 0`, while PowerShell uses `if (-not (Test-Path $Flag)) { exit 0 }`.

### What do the color codes 108 and 173 represent in the output?

These are 256-color ANSI escape codes. Code **108** produces a green-ish hue used for standard modes (`full`, `debug`, etc.), while code **173** produces an amber/orange color specifically reserved for `ultra` mode to make it visually distinct and alert the user to the heightened operational state.

### Can I use these scripts outside of my shell prompt?

Yes. Both [`ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-statusline.sh) and `ponytail-statusline.ps1` write to standard output using direct console writes (`printf` in Bash, `[Console]::Write` in PowerShell), making them suitable for integration with **tmux** status bars, **screen** hardstatus lines, or any system that can execute shell commands to generate status text.