How to Configure the Default Ponytail Intensity Mode Using Environment Variables or Config Files

You can set Ponytail's default intensity mode via the PONYTAIL_DEFAULT_MODE environment variable (taking precedence) or by creating a config.json file in your XDG config directory with a defaultMode property.

Ponytail supports three intensity levels—lite, full, and ultra—that control how aggressively the tool processes your code. Rather than passing --intensity with every command, you can establish a persistent default through environment variables or a configuration file. The resolution logic is implemented in [hooks/ponytail-config.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js), which both the CLI and MCP server consult during startup.

How the Default Mode Resolution Works

Ponytail evaluates configuration sources in strict priority order:

1. Environment variable PONYTAIL_DEFAULT_MODE — checked first; overrides all other settings
2. Config file ponytail/config.json — located via XDG Base Directory specification
3. Built-in fallback — full if neither source provides a value

This hierarchy allows per-command overrides while still supporting persistent user preferences.

Method 1: Configure with the PONYTAIL_DEFAULT_MODE Environment Variable

The fastest way to change the default mode is setting this variable. The value must be exactly lite, full, or ultra—case-sensitive.

Temporary (single command)

PONYTAIL_DEFAULT_MODE=lite ponytail analyze ./src

Session-wide (current shell)

export PONYTAIL_DEFAULT_MODE=ultra
ponytail analyze ./src
ponytail report           # also uses ultra

Permanent (shell profile)

Add to ~/.bashrc, ~/.zshrc, or equivalent:

export PONYTAIL_DEFAULT_MODE=full

The environment variable is read early in [ponytail-config.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) via process.env.PONYTAIL_DEFAULT_MODE before any config file parsing occurs.

Method 2: Configure with a JSON Config File

For persistent, cross-session defaults without environment pollution, create a config.json file.

Config file location

Ponytail follows the XDG Base Directory specification:

• $XDG_CONFIG_HOME/ponytail/config.json (if XDG_CONFIG_HOME is set)
• $HOME/.config/ponytail/config.json (fallback)

Config file format

{
  "defaultMode": "full"
}

Only the defaultMode key is currently recognized. Additional keys are ignored but preserved for forward compatibility.

Setup commands

# Create the config directory

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/ponytail"

# Write the config file

cat > "${XDG_CONFIG_HOME:-$HOME/.config}/ponytail/config.json" <<'EOF'
{
  "defaultMode": "lite"
}
EOF

If PONYTAIL_DEFAULT_MODE is unset, [ponytail-config.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) reads this file via standard filesystem APIs and parses it with JSON.parse().

Method 3: Combine Both Approaches

You can use the config file for your baseline preference and override per-command when needed:

# Config file sets default to "full"

export PONYTAIL_DEFAULT_MODE=lite  # temporarily override

ponytail analyze ./critical-path   # runs in lite mode

ponytail analyze ./tests           # also lite mode

unset PONYTAIL_DEFAULT_MODE        # revert to config file default (full)

ponytail analyze ./docs            # runs in full mode

This pattern appears in the test suite at [tests/opencode-plugin.test.js](https://github.com/DietrichGebert/ponytail/blob/main/tests/opencode-plugin.test.js), which clears the environment variable to ensure isolated test behavior.

Validation and Error Handling

Ponytail validates the mode value at configuration load time. Invalid values trigger an error before any processing begins:

$ PONYTAIL_DEFAULT_MODE=invalid ponytail analyze ./src
Error: Invalid PONYTAIL_DEFAULT_MODE: "invalid". Must be one of: lite, full, ultra

Similarly, malformed JSON in the config file produces a parse error with the file path:

Error: Failed to parse config at ~/.config/ponytail/config.json: Unexpected token }

Where Configuration Is Used

Component	File Path	Role
Config loader	[hooks/ponytail-config.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)	Reads env var and config file, resolves default mode
MCP server	[ponytail-mcp/index.js](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/index.js)	Exposes --intensity CLI flag, falls back to config loader
Git hooks	hooks/ directory	Pre-commit and other hooks use resolved default
Tests	[tests/hooks.test.js](https://github.com/DietrichGebert/ponytail/blob/main/tests/hooks.test.js)	Validates env var and config file behavior
Plugin tests	[tests/opencode-plugin.test.js](https://github.com/DietrichGebert/ponytail/blob/main/tests/opencode-plugin.test.js)	Demonstrates environment cleanup patterns

Summary

• Use PONYTAIL_DEFAULT_MODE for quick, temporary, or shell-specific defaults
• Use ~/.config/ponytail/config.json with {"defaultMode": "mode"} for persistent, cross-shell configuration
• Environment variable takes precedence over config file when both are present
• Valid modes are lite, full, and ultra; any other value causes a startup error
• The resolution logic lives in [hooks/ponytail-config.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) and is shared across all Ponytail entry points

Frequently Asked Questions

What happens if I set both the environment variable and the config file?

The PONYTAIL_DEFAULT_MODE environment variable always wins. The config file is only consulted when the environment variable is undefined or empty. This precedence order is hardcoded in [ponytail-config.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).

Can I use a config file location other than the XDG directories?

No. Ponytail strictly follows the XDG Base Directory specification. It does not support custom config file paths via command-line flags or additional environment variables. If you need per-project configuration, consider using directory-specific environment variable exports with a tool like direnv.

What is the default if I configure nothing?

Ponytail falls back to full mode when neither PONYTAIL_DEFAULT_MODE nor a valid config file is present. This default is defined as a constant in [ponytail-config.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) and is used throughout the codebase when no user preference is detected.

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