How to Set a Default Ponytail Intensity Level: Environment Variable vs. Config File

Set the default Ponytail intensity using the PONYTAIL_DEFAULT_MODE environment variable or a defaultMode key in ~/.config/ponytail/config.json, with the environment variable taking precedence.

Ponytail's intensity level (also called mode) controls how aggressively lazy-senior-dev rules are applied to your code. You can configure the default intensity permanently or per-session using two methods built into the DietrichGebert/ponytail source code. This guide explains both configuration options, their precedence order, and how to validate your settings.

Understanding Ponytail Intensity Levels

Ponytail supports four intensity modes:

Mode	Description
lite	Minimal rule enforcement
full	Standard lazy-senior-dev rules (built-in default)
ultra	Maximum strictness
off	Disable all rules

These modes determine which transformations and suggestions Ponytail applies during code review and generation.

Method 1: Environment Variable (Highest Precedence)

The PONYTAIL_DEFAULT_MODE environment variable overrides all other settings. This is ideal for CI/CD pipelines, temporary testing, or machine-specific configurations.

Bash/Zsh (Linux, macOS, WSL)

export PONYTAIL_DEFAULT_MODE=ultra

PowerShell (Windows)

$env:PONYTAIL_DEFAULT_MODE="lite"

Command Prompt (Windows)

set PONYTAIL_DEFAULT_MODE=full

The environment variable is documented in README.md at line 275 and processed during runtime initialization.

Method 2: User Config File (Fallback)

When PONYTAIL_DEFAULT_MODE is unset, Ponytail reads defaultMode from a JSON configuration file. This provides persistent, user-specific defaults.

Unix/Linux/macOS

Create or edit ~/.config/ponytail/config.json:

{
  "defaultMode": "lite"
}

Windows

Create or edit %APPDATA%\ponytail\config.json:

{
  "defaultMode": "off"
}

The config file path follows XDG conventions on Unix systems and standard Windows application data directories.

How Mode Resolution Works

The resolution logic lives in __init__.py at line 58. The code implements this priority order:

1. Check PONYTAIL_DEFAULT_MODE environment variable
2. If absent, read defaultMode from config file
3. If both are absent, fall back to built-in default: full

Internally, the _normalize_config_mode() function validates and normalizes the mode string, while _default_mode holds the resolved value.

Verifying Your Current Intensity

To confirm which mode is active, use the /ponytail command as described in .opencode/command/ponytail-help.md:

ponytail /ponytail

Without arguments, this echoes the effective intensity level. You can also use it to change modes dynamically for the current session.

MCP and Skill-Based Configuration

For hosts using the Model Context Protocol (MCP), the mode resolution is reused across clients. The ponytail-mcp/README.md shows how hooks/ponytail-config.js integrates this logic.

One-off environment setup for skill-based hosts (from skills/ponytail-help/SKILL.md):

export PONYTAIL_DEFAULT_MODE=ultra && ponytail /ponytail

Summary

• Environment variable PONYTAIL_DEFAULT_MODE wins over all other settings — use it for temporary or CI-specific overrides
• Config file ~/.config/ponytail/config.json (or %APPDATA%\ponytail\config.json) provides persistent per-user defaults
• Built-in fallback is full when neither is configured
• Resolution happens in __init__.py with _normalize_config_mode() and _default_mode
• Verify with ponytail /ponytail

Frequently Asked Questions

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

The environment variable PONYTAIL_DEFAULT_MODE takes precedence. The config file is only read when the environment variable is absent or empty.

Can I change the intensity without restarting my editor?

Yes. The /ponytail command accepts mode arguments to change intensity dynamically. Run ponytail /ponytail ultra to switch to ultra mode for the current session.

Where is the config file on macOS?

Use ~/.config/ponytail/config.json. If the ~/.config directory doesn't exist, create it first: mkdir -p ~/.config/ponytail.

What values are valid for the default mode?

Only four values are accepted: lite, full, ultra, and off. Invalid values trigger the built-in fallback to full after normalization in _normalize_config_mode().

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