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

> Learn how to set your default Ponytail intensity level using environment variables or config files. Discover which method takes precedence for optimal configuration.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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)

```bash
export PONYTAIL_DEFAULT_MODE=ultra

```

### PowerShell (Windows)

```powershell
$env:PONYTAIL_DEFAULT_MODE="lite"

```

### Command Prompt (Windows)

```cmd
set PONYTAIL_DEFAULT_MODE=full

```

The environment variable is documented in [`README.md`](https://github.com/DietrichGebert/ponytail/blob/main/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`:

```json
{
  "defaultMode": "lite"
}

```

### Windows

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

```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`](https://github.com/DietrichGebert/ponytail/blob/main/__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`](https://github.com/DietrichGebert/ponytail/blob/main/.opencode/command/ponytail-help.md):

```bash
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`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/README.md) shows how [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) integrates this logic.

One-off environment setup for skill-based hosts (from [`skills/ponytail-help/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-help/SKILL.md)):

```bash
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`](https://github.com/DietrichGebert/ponytail/blob/main/__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()`.