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

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, encapsulates the directory resolution logic:

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 and 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)

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)

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

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 (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)

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

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:

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:

#!/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:

$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 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 and hooks/ponytail-statusline.ps1 providing native access.
• The file is automatically removed during uninstallation via 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 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 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.

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