How to Set the Default Ponytail Mode via Environment Variables

Set the PONYTAIL_DEFAULT_MODE environment variable to one of the runtime-compatible modes (off, lite, full, or ultra) before invoking Ponytail, and the application will use that value as the session default instead of checking the configuration file.

Ponytail uses a layered configuration resolution strategy that prioritizes environment variables over file-based settings. According to the DietrichGebert/ponytail source code, you can override the default operating mode by exporting PONYTAIL_DEFAULT_MODE with a valid runtime mode value. This approach ensures consistent behavior across different shells and scripting environments without modifying configuration files.

Understanding Ponytail's Mode Resolution Hierarchy

The default mode resolution logic is implemented in hooks/ponytail-config.js. This file defines a three-tier priority system that determines which operating mode Ponytail adopts at startup.

The Three-Layer Resolution Strategy

Ponytail evaluates potential default modes in the following strict order of precedence:

1. Environment variable – PONYTAIL_DEFAULT_MODE (runtime-level only) – ponytail-config.js:76-84
2. Configuration file – $XDG_CONFIG_HOME/ponytail/config.json (or its platform-specific fallbacks) – ponytail-config.js:86-94
3. Hard-coded fallback – 'full' – ponytail-config.js:99-100

When the environment variable is present, Ponytail reads its value, normalizes it to lowercase, and validates it against the list of runtime-compatible modes. If validation passes, the configuration file is never consulted.

Setting PONYTAIL_DEFAULT_MODE in Different Shells

You can export the environment variable using the syntax appropriate for your operating system or scripting environment. The variable must be set before the ponytail process starts.

Bash and Zsh (Linux/macOS)

export PONYTAIL_DEFAULT_MODE=lite
ponytail

Options for the value include: off, lite, full, or ultra.

Windows PowerShell

$env:PONYTAIL_DEFAULT_MODE = "ultra"
ponytail

Windows Command Prompt

set PONYTAIL_DEFAULT_MODE=full
ponytail

Python Subprocess

When spawning Ponytail from a Python script, set the variable in os.environ before calling the process:

import os
import subprocess

os.environ["PONYTAIL_DEFAULT_MODE"] = "off"
subprocess.run(["ponytail"])

Valid Mode Values and Validation Logic

Only the runtime modes (off, lite, full, ultra) are accepted as defaults. The implementation in hooks/ponytail-config.js explicitly filters the input through a validation function that checks against this whitelist.

The special review mode is reserved for session-only use. If you attempt to set PONYTAIL_DEFAULT_MODE=review, the validation logic ignores it and Ponytail proceeds to the next resolution step (the configuration file or the hard-coded fallback). This restriction prevents unattended sessions from starting in an interactive review state.

Values are normalized to lowercase before validation, so LITE and Lite are both valid and resolve to lite.

Troubleshooting Invalid Values

If you specify an invalid value such as review, debug, or a typo like ulrta, Ponytail silently ignores the environment variable. The application does not throw an error; instead, it falls back to checking $XDG_CONFIG_HOME/ponytail/config.json. If that file is missing or also contains an invalid mode, Ponytail defaults to 'full' mode.

To verify which mode is active during troubleshooting, check the runtime state tracking implemented in hooks/ponytail-mode-tracker.js, which consumes the resolved default from the configuration logic.

Summary

• PONYTAIL_DEFAULT_MODE is the highest-priority source for setting Ponytail's default operating mode.
• Valid values are strictly limited to: off, lite, full, and ultra.
• The variable is case-insensitive but is normalized to lowercase internally.
• The review mode is explicitly rejected when provided via environment variables to prevent unintended interactive sessions.
• Invalid or missing values trigger a fallback chain: config file → hard-coded 'full' default.
• Implementation resides in hooks/ponytail-config.js with validation logic at lines 76-84.

Frequently Asked Questions

What values are valid for PONYTAIL_DEFAULT_MODE?

The only accepted values are the runtime-compatible modes: off, lite, full, and ultra. These strings are validated against a whitelist in hooks/ponytail-config.js. The review mode is intentionally excluded from environment variable configuration because it requires interactive session management.

Why is the review mode ignored when set via environment variables?

The review mode is designed for session-only use and requires manual oversight. According to the validation comment in hooks/ponytail-config.js, allowing review as a default would risk starting unattended processes in an interactive state. Consequently, if PONYTAIL_DEFAULT_MODE=review is detected, Ponytail treats it as an invalid value and proceeds to the next configuration source.

Does the environment variable override the config.json file?

Yes. The resolution hierarchy places PONYTAIL_DEFAULT_MODE at the highest priority (level 1), while $XDG_CONFIG_HOME/ponytail/config.json is checked only if the environment variable is absent or invalid (level 2). If the environment variable contains a valid runtime mode, the configuration file is never read for the default mode setting.

How do I verify which mode Ponytail is actually using?

Ponytail tracks the active mode through hooks/ponytail-mode-tracker.js, which consumes the resolved default from the configuration logic. You can confirm the effective mode by checking the application's runtime state output or by temporarily setting an invalid environment variable value to observe whether the system falls back to your config file's setting.

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