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

You can switch Ponytail intensity levels between lite, full, and ultra using the PONYTAIL_DEFAULT_MODE environment variable, a 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 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, 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.

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 file in the Ponytail configuration directory.

The getDefaultMode() function in 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:

{
  "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, 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").

ponytail-mcp --mode full

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

{
  "mode": "lite"
}

How Mode Resolution Works

The central selection logic lives in ponytail-mcp/instructions.js. The resolveMode(requested) function normalizes caller input via normalizeMode from 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
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
• Switch modes via environment variable (PONYTAIL_DEFAULT_MODE), config file (config.json), or CLI argument (--mode)
• Resolution priority follows: explicit argument → environment variable → config file → default "full"
• Key files: ponytail-mcp/instructions.js (mode logic), hooks/ponytail-config.js (default resolution), 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.

Does the environment variable override the config file?

Yes. The getDefaultMode() function in hooks/ponytail-config.js checks process.env.PONYTAIL_DEFAULT_MODE before loading the 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 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.

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