How to Configure the Default Mode for Ponytail: Environment Variables and Config Files

You can configure Ponytail’s default operating mode by setting the PONYTAIL_DEFAULT_MODE environment variable (highest priority), defining a defaultMode field in your platform-specific config.json, or relying on the built-in fallback value of full.

Ponytail determines its startup behavior through a hierarchical resolution system implemented in hooks/ponytail-config.js. According to the DietrichGebert/ponytail source code, the tool resolves the default mode through three distinct priority levels, accepting only the runtime modes (off, lite, full, ultra) while explicitly excluding the session-only review mode.

The Three-Level Resolution Hierarchy

Ponytail’s getDefaultMode() function implements a cascading lookup strategy. The first valid source found determines the starting mode for any new Ponytail process.

1. Environment Variable (Highest Priority)

When the PONYTAIL_DEFAULT_MODE environment variable is defined, its value overrides all other configuration sources. The variable is read at lines 78–84 in hooks/ponytail-config.js, where the code checks for the presence of the variable and validates that it contains an allowed runtime mode.

2. User Configuration File

If the environment variable is absent, Ponytail queries a JSON configuration file. The helper function getConfigPath() (lines 67–70) resolves the platform-specific location:

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

The getDefaultMode() function then reads the defaultMode property from this file at lines 86–94.

3. Built-in Fallback

If neither the environment variable nor a valid config entry exists, Ponytail falls back to the constant DEFAULT_MODE = 'full' defined at line 16 in hooks/ponytail-config.js.

Setting the Default Mode via Environment Variable

Configuring via environment variable takes effect immediately for new processes without modifying files. Use the appropriate syntax for your shell:

# Bash/Zsh

export PONYTAIL_DEFAULT_MODE=lite

# Windows CMD

set PONYTAIL_DEFAULT_MODE=lite

# PowerShell

$env:PONYTAIL_DEFAULT_MODE = "lite"

The validation logic at line 82 ensures that only off, lite, full, or ultra are accepted; invalid values trigger a fallback to the next resolution level.

Configuring the Default Mode via Config File

For persistent configuration across system restarts, create or edit the config.json file. First, ensure the directory exists:

mkdir -p ~/.config/ponytail

Then create the file with your desired default:

cat > ~/.config/ponytail/config.json <<EOF
{
  "defaultMode": "ultra",
  "quietStartup": true,
  "hideStatus": false
}
EOF

Alternatively, use the programmatic API writeDefaultMode(mode) exported from ponytail-config.js. This method calls normalizeMode() (lines 20–24) to validate inputs before persisting them to disk, ensuring only valid runtime modes are written.

Programmatic Configuration Examples

When building tools on top of Ponytail, you can query or modify the default mode directly from Node.js.

Querying the Current Effective Default

const cfg = require('./hooks/ponytail-config');
console.log('Effective default mode:', cfg.getDefaultMode());
// Output: "full" (or whatever is resolved from env/config/fallback)

Changing the Default Mode Programmatically

const cfg = require('./hooks/ponytail-config');

// Attempts to write to the user config file
if (cfg.writeDefaultMode('lite')) {
  console.log('Default mode updated to lite');
} else {
  console.error('Invalid mode; must be off|lite|full|ultra');
}

Using Environment Variables in Scripts

#!/usr/bin/env bash
export PONYTAIL_DEFAULT_MODE=off
node -e "console.log(require('./hooks/ponytail-config').getDefaultMode())"

# Prints: "off"

Valid Mode Constraints

The normalizeMode() function enforces strict validation: only runtime-level modes (off, lite, full, ultra) are eligible as defaults. The review mode is deliberately excluded at line 82 because it is designed for session-only usage within hooks/ponytail-mode-tracker.js. Attempting to set an invalid mode via any configuration method results in the validator rejecting the value and triggering the fallback mechanism.

Summary

• Environment Variable: Set PONYTAIL_DEFAULT_MODE to off, lite, full, or ultra for immediate, process-level configuration.
• Config File: Create config.json in your platform-specific config directory (~/.config/ponytail/ on Linux/macOS, %APPDATA%\ponytail\ on Windows) for persistent settings.
• Fallback: The constant DEFAULT_MODE = 'full' at line 16 ensures the application never starts without a valid mode.
• Validation: Both normalizeMode() (lines 20–24) and the environment variable checker (line 82) exclude the review mode and invalid strings.

Frequently Asked Questions

What happens if I don’t configure a default mode?

If you do not set the PONYTAIL_DEFAULT_MODE environment variable and no config.json file exists (or it lacks a defaultMode entry), Ponytail uses the built-in constant DEFAULT_MODE = 'full' defined at line 16 in hooks/ponytail-config.js. This ensures the application always starts with a predictable baseline behavior.

Can I set "review" as the default mode?

No. The validation logic at line 82 in hooks/ponytail-config.js explicitly filters out the review mode when resolving defaults. Only the runtime modes (off, lite, full, ultra) are permitted; review is restricted to session-level usage within hooks/ponytail-mode-tracker.js.

Where is the configuration file stored on different operating systems?

On Linux and macOS, Ponytail checks ~/.config/ponytail/config.json (or $XDG_CONFIG_HOME/ponytail/config.json if the XDG variable is defined). On Windows, the path resolves to %APPDATA%\ponytail\config.json. The getConfigPath() helper at lines 67–70 handles the platform detection automatically.

How do I programmatically change the default mode from my Node.js application?

Import ponytail-config.js and call writeDefaultMode(mode), passing one of the valid runtime strings. This function validates the input through normalizeMode() (lines 20–24) and writes the change to the user config file if valid, returning a boolean indicating success or failure.

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