How to Change the Default Ponytail Mode: Environment Variables, Config Files, and Commands

Ponytail determines its default intensity level through a three-step priority chain: first checking the PONYTAIL_DEFAULT_MODE environment variable, then falling back to the defaultMode field in config.json, and finally defaulting to full if neither is set.

In the DietrichGebert/ponytail repository, the default mode dictates which intensity level (off, lite, full, or ultra) activates automatically when you start a new session. Understanding how to change the default Ponytail mode allows you to customize the tool's behavior permanently without passing flags to every invocation.

Understanding the Priority Chain

Ponytail resolves the default mode using a strict hierarchy implemented in [hooks/ponytail-config.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js). The getDefaultMode() function evaluates three sources in order:

1. Environment variable PONYTAIL_DEFAULT_MODE — highest precedence
2. User configuration file config.json — located in the platform-specific config directory
3. Built-in constant DEFAULT_MODE — hardcoded to 'full'

Only runtime modes (off, lite, full, ultra) are valid defaults. The review mode is session-only and cannot be set as a permanent default.

Method 1: Set the Environment Variable

Setting the environment variable provides the fastest way to change the default Ponytail mode and overrides any configuration file settings. This variable is read each time Ponytail initializes.

For Bash or Zsh:

export PONYTAIL_DEFAULT_MODE=lite

For Windows Command Prompt:

set PONYTAIL_DEFAULT_MODE=ultra

For PowerShell:

$env:PONYTAIL_DEFAULT_MODE = "off"

Method 2: Edit the Configuration File

For persistent changes that persist across shell sessions, modify the config.json file. The writeDefaultMode() function in hooks/ponytail-config.js handles validation and I/O operations for this file.

Locate your configuration directory based on your operating system:

• Linux/macOS: ~/.config/ponytail/config.json (or $XDG_CONFIG_HOME/ponytail/config.json if set)
• Windows: %APPDATA%\ponytail\config.json

Create or edit the file with the following structure:

{
  "defaultMode": "ultra",
  "quietStartup": true,
  "hideStatus": false
}

Ponytail validates that the defaultMode value matches one of the allowed runtime intensities before applying it.

Method 3: Use the /ponytail default Command

When running Ponytail within a compatible host environment (such as the Pi extension), you can change the default mode conversationally. The command handler in [pi-extension/index.js](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) invokes writeDefaultMode() to update config.json directly.

Example usage:

/ponytail default lite

This method performs the same validation as manual file editing and immediately affects subsequent sessions.

Validating Your Current Default

To verify which mode Ponytail will use for the next session, inspect the resolved default programmatically:

const { getDefaultMode } = require("./hooks/ponytail-config.js");

console.log("Current default mode:", getDefaultMode());
// Output: "lite", "full", "ultra", or "off" depending on your configuration

You can also programmatically set the default from a Node.js script:

const { writeDefaultMode, getDefaultMode } = require("./hooks/ponytail-config.js");

writeDefaultMode("ultra");
console.log("Updated default:", getDefaultMode());

The [hooks/ponytail-mode-tracker.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) file activates this default value on the first prompt when no session flag file exists, ensuring your preference applies immediately.

Summary

• Highest priority: Set the PONYTAIL_DEFAULT_MODE environment variable for immediate, session-specific overrides.
• Persistent storage: Edit config.json in your platform's configuration directory (~/.config/ponytail/ on Unix, %APPDATA%\ponytail\ on Windows).
• Interactive change: Use /ponytail default <mode> in supported host environments to invoke writeDefaultMode().
• Fallback behavior: If no configuration exists, Ponytail defaults to full intensity as defined in hooks/ponytail-config.js.

Frequently Asked Questions

Can I set "review" mode as the default?

No. The review mode is session-only and excluded from the validation logic in getDefaultMode(). Only off, lite, full, and ultra are valid values for the default configuration.

Where exactly is the configuration file located on my system?

Ponytail searches for config.json using platform-specific logic. On Linux and macOS, it checks $XDG_CONFIG_HOME/ponytail/ first, then falls back to ~/.config/ponytail/. On Windows, it uses %APPDATA%\ponytail\. The file must contain a JSON object with a defaultMode string field.

Does the environment variable override an existing config file?

Yes. The resolution chain in hooks/ponytail-config.js checks process.env.PONYTAIL_DEFAULT_MODE before reading the filesystem. If the environment variable is present and valid, Ponytail skips the configuration file entirely and uses that value.

What happens if I specify an invalid mode in the config file?

The writeDefaultMode() function validates inputs against the allowed set of runtime modes. If you manually edit config.json with an invalid value (such as "aggressive" or "review"), getDefaultMode() will ignore it and fall back to the built-in full default.

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