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

> Control Ponytail's default intensity mode using the PONYTAIL_DEFAULT_MODE environment variable or config.json file for personalized settings.

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

---

**You can set Ponytail's default intensity mode via the `PONYTAIL_DEFAULT_MODE` environment variable (taking precedence) or by creating a [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/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)](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`](https://github.com/DietrichGebert/ponytail/blob/main/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)

```bash
PONYTAIL_DEFAULT_MODE=lite ponytail analyze ./src

```

### Session-wide (current shell)

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

```

### Permanent (shell profile)

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

```bash
export PONYTAIL_DEFAULT_MODE=full

```

The environment variable is read early in [[`ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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

```json
{
  "defaultMode": "full"
}

```

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

### Setup commands

```bash

# 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/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:

```bash

# 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)](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:

```bash
$ 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:

```bash
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)](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)](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/index.js) | Exposes `--intensity` CLI flag, falls back to config loader |
| **Git hooks** | [`hooks/`](https://github.com/DietrichGebert/ponytail/tree/main/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)](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)](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)](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/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/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.