# How to Switch Ponytail Intensity Levels: Environment, Config, and CLI Methods

> Master Ponytail intensity levels lite full and ultra using environment variables config json or the CLI argument Learn how to optimize your Ponytail setup for peak performance

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

---

**You can switch Ponytail intensity levels between `lite`, `full`, and `ultra` using the `PONYTAIL_DEFAULT_MODE` environment variable, a [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) configuration file, or the `--mode` CLI argument.**

The DietrichGebert/ponytail repository provides an MCP (Model Context Protocol) server that generates coding rulesets with variable guidance intensity. Switching Ponytail intensity levels controls whether the emitted ruleset provides minimal scaffolding (`lite`), standard assistance (`full`), or comprehensive restrictions (`ultra`).

## Understanding Ponytail Intensity Levels

Ponytail runs with three **runtime intensity levels** that determine which parts of the generated ruleset are emitted:

- **`lite`** — Minimal guidance and restrictions
- **`full`** — Standard assistance (the hard-coded fallback default)
- **`ultra`** — Comprehensive restrictions and detailed rules

The `MODES` array in [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) defines these supported intensities, while the `resolveMode()` function handles the selection logic.

## Method 1: Environment Variable (PONYTAIL_DEFAULT_MODE)

The fastest way to set a persistent default intensity is via the **environment variable** `PONYTAIL_DEFAULT_MODE`.

According to [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js), the `getDefaultMode()` function checks `process.env.PONYTAIL_DEFAULT_MODE` as the first priority in its resolution chain. Valid values are `off`, `lite`, `full`, or `ultra`.

```bash
export PONYTAIL_DEFAULT_MODE=lite
ponytail  # starts with lite intensity

```

If you set the value to `off`, Ponytail disables the ruleset emission entirely.

## Method 2: Configuration File (config.json)

For user-specific defaults that persist across sessions, create a [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file in the Ponytail configuration directory.

The `getDefaultMode()` function in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) searches for this file in platform-specific locations:

- **Linux/macOS**: `$XDG_CONFIG_HOME/ponytail/config.json` (or `~/.config/ponytail/config.json` as fallback)
- **Windows**: `%APPDATA%\ponytail\config.json`

Set the `defaultMode` key to your preferred intensity:

```json
{
  "defaultMode": "ultra"
}

```

After saving the file, simply invoking `ponytail` loads the `ultra` intensity ruleset without additional flags.

## Method 3: CLI Arguments and Prompt Parameters

For temporary, one-time overrides, pass the `--mode` flag when starting the MCP server.

In [`ponytail-mcp/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/index.js), the command-line argument schema validates the `mode` parameter against `MODES` and passes the value directly to `buildInstructions()`. If omitted, the server resolves the mode using the fallback chain (environment variable → config file → `"full"`).

```bash
ponytail-mcp --mode full

```

When interacting via the prompt API, include the mode in your request payload:

```json
{
  "mode": "lite"
}

```

## How Mode Resolution Works

The central selection logic lives in [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js). The `resolveMode(requested)` function normalizes caller input via `normalizeMode` from [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) and implements the following fallback sequence:

1. The explicitly requested mode (from CLI or prompt arguments)
2. The `PONYTAIL_DEFAULT_MODE` environment variable
3. The `defaultMode` value from [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json)
4. The hard-coded fallback `"full"` (unless set to `off`)

The `buildInstructions(requested)` function then invokes `getPonytailInstructions(resolveMode(requested))` to retrieve the final ruleset text based on the resolved intensity.

## Summary

- Ponytail supports three intensity levels: `lite`, `full`, and `ultra`, defined in [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js)
- Switch modes via **environment variable** (`PONYTAIL_DEFAULT_MODE`), **config file** ([`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json)), or **CLI argument** (`--mode`)
- Resolution priority follows: explicit argument → environment variable → config file → default `"full"`
- Key files: [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) (mode logic), [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) (default resolution), [`ponytail-mcp/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/index.js) (CLI handling)

## Frequently Asked Questions

### What are the valid Ponytail intensity levels?

The valid runtime intensity levels are `lite`, `full`, and `ultra`. Additionally, you can set the mode to `off` to disable ruleset emission entirely. These values are defined in the `MODES` constant within [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js).

### Does the environment variable override the config file?

Yes. The `getDefaultMode()` function in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) checks `process.env.PONYTAIL_DEFAULT_MODE` before loading the [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file. Only if the environment variable is unset does Ponytail read the configuration file, falling back to `"full"` only if neither is present.

### Where does Ponytail store its configuration file on Windows?

On Windows, Ponytail looks for [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) at `%APPDATA%\ponytail\config.json`. The `getDefaultMode()` function resolves this path through standard Windows environment variables before attempting to read the file.

### Can I override the default mode for a single run without changing config?

Yes. Pass the `--mode` flag directly when starting the server: `ponytail-mcp --mode ultra`. This explicit argument takes precedence over both the environment variable and configuration file settings for that specific execution.