# Where Is the Ponytail Mode Flag File Stored? Cross-Platform Path Guide

> Find where the Ponytail mode flag file is stored across different platforms. Learn the default paths for both POSIX and Windows systems for the .ponytail-active file.

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

---

**Ponytail stores its mode flag in a hidden file named `.ponytail-active` inside the directory returned by `getClaudeDir()`, defaulting to `~/.claude/.ponytail-active` on POSIX systems and the equivalent user profile path on Windows.**

The open-source Ponytail project by DietrichGebert persists its active state—whether **off**, **lite**, **full**, or **ultra**—using a simple filesystem marker. Knowing exactly where this **Ponytail mode flag file** lives across macOS, Linux, and Windows enables manual inspection, scripting, and troubleshooting.

## Resolution Logic and Default Paths

Ponytail determines the storage location through a centralized configuration resolver that prioritizes environment variables over platform-specific defaults.

### Understanding `getClaudeDir()`

The helper function **`getClaudeDir()`**, defined in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js), encapsulates the directory resolution logic:

```js
function getClaudeDir() {
  // CLAUDE_CONFIG_DIR overrides the default location.
  return process.env.CLAUDE_CONFIG_DIR ||
         path.join(os.homedir(), '.claude');
}

```

This function is the single source of truth used throughout the codebase, including [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) and [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js). The final flag path is constructed by joining this directory with the constant filename **`.ponytail-active`**.

### Platform-Specific Default Locations

When the `CLAUDE_CONFIG_DIR` environment variable is unset, Ponytail falls back to OS-specific home directories via Node.js's `os.homedir()`:

- **macOS and Linux**: `$HOME/.claude/.ponytail-active`
- **Windows**: `%USERPROFILE%\.claude\.ponytail-active` (e.g., `C:\Users\Username\.claude\.ponytail-active`)

For VS Code Copilot extensions, the system additionally checks the `COPILOT_PLUGIN_DATA` environment variable before falling back to `getClaudeDir()`, resulting in a potential path of `${COPILOT_PLUGIN_DATA}/.ponytail-active`.

## Source Code Implementation

The flag file handling is distributed across several modules, each responsible for different lifecycle stages.

### Core Configuration ([`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js))

This file exports `getClaudeDir()`, which governs all path resolution. The comment in the source explicitly documents the precedence: `CLAUDE_CONFIG_DIR` overrides the default `~/.claude` location.

### Runtime Flag Management ([`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js))

The runtime module declares the flag filename as a constant and constructs the full path:

```js
const STATE_FILE = '.ponytail-active';
const flagPath = path.join(getClaudeDir(), STATE_FILE);

```

This path is used for both reading the current mode and persisting state changes.

### Shell Integration Scripts

Platform-specific scripts access the same file using native syntax:

- **[`hooks/ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-statusline.sh)** (Bash/Zsh): Reads `"${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.ponytail-active"`
- **`hooks/ponytail-statusline.ps1`** (PowerShell): Constructs `$ClaudeDir` then appends `".ponytail-active"`

### Uninstall Cleanup ([`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js))

The removal logic explicitly targets the flag file to ensure clean uninstallation:

```js
removeIfExists(path.join(getClaudeDir(), '.ponytail-active'));

```

## Practical Access Patterns

Retrieve or modify the Ponytail mode flag file using these platform-appropriate methods.

### Node.js (Cross-Platform)

Use the project's own configuration resolver to ensure consistency:

```js
const { getClaudeDir } = require('./hooks/ponytail-config');
const path = require('path');

const flagPath = path.join(getClaudeDir(), '.ponytail-active');
console.log('Ponytail flag:', flagPath);
// Output on macOS/Linux: /home/username/.claude/.ponytail-active
// Output on Windows: C:\Users\username\.claude\.ponytail-active

```

### POSIX Shell (macOS/Linux)

Check the current mode directly without loading Node.js:

```sh
#!/usr/bin/env bash
FLAG="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.ponytail-active"

if [ -f "$FLAG" ]; then
  cat "$FLAG"   # Outputs: off, lite, full, or ultra

else
  echo "Ponytail not active"
fi

```

### PowerShell (Windows)

Update the mode programmatically on Windows systems:

```powershell
$ClaudeDir = $env:CLAUDE_CONFIG_DIR ?? (Join-Path $env:USERPROFILE '.claude')
$FlagPath = Join-Path $ClaudeDir '.ponytail-active'
Set-Content -Path $FlagPath -Value 'ultra'

```

## Summary

- The **Ponytail mode flag file** is always named `.ponytail-active` and resides within the Claude configuration directory.
- The **`getClaudeDir()`** function in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) resolves the parent directory, checking `CLAUDE_CONFIG_DIR` before defaulting to `~/.claude` (or the Windows equivalent).
- **Cross-platform compatibility** is achieved through Node.js's `os.homedir()`, with platform-specific shell scripts in [`hooks/ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-statusline.sh) and `hooks/ponytail-statusline.ps1` providing native access.
- The file is automatically removed during uninstallation via [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js).

## Frequently Asked Questions

### What is the exact filename of the Ponytail mode flag file?

The filename is **`.ponytail-active`**. This is defined as the constant `STATE_FILE` in [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) and is hardcoded across all platform-specific shell scripts and the uninstaller.

### Can I change where Ponytail stores its mode flag file?

Yes. Set the **`CLAUDE_CONFIG_DIR`** environment variable to your desired directory. The `getClaudeDir()` function checks this variable first before falling back to the default `~/.claude` location. The flag file will be created at `$CLAUDE_CONFIG_DIR/.ponytail-active`.

### How do I check the current Ponytail mode from the command line?

On macOS or Linux, run: `cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.ponytail-active"`. On Windows PowerShell, use: `Get-Content (Join-Path ($env:CLAUDE_CONFIG_DIR ?? (Join-Path $env:USERPROFILE '.claude')) '.ponytail-active')`. If the file does not exist, Ponytail is not currently active.

### Does Ponytail remove the flag file when uninstalling?

Yes. The [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) script explicitly calls `removeIfExists(path.join(getClaudeDir(), '.ponytail-active'))` to ensure the mode flag is cleaned up and does not persist as orphaned state after removal.