How to Configure Ponytail Mode to Ultra: 3 Methods Explained

To configure Ponytail mode to ultra, set the PONYTAIL_DEFAULT_MODE environment variable to ultra, create a config.json file with "defaultMode": "ultra", or execute the /ponytail ultra slash command to enable the strictest skill content filtering.

Ponytail is a plugin that injects specialized "Ponytail" skill content into LLM contexts, with an ultra mode that applies the most aggressive filtering available. According to the DietrichGebert/ponytail source code, the runtime mode determines which sections of skills/ponytail/SKILL.md are presented to the model, and can be configured persistently through environment variables or configuration files, or changed dynamically via slash commands.

Understanding Ponytail Runtime Modes

Ponytail implements a runtime mode system defined in the RUNTIME_MODES constant (lines 30-34 of __init__.py). The available modes include off, lite, full, and ultra. When set to ultra, the plugin applies the strictest filtering via _filter_skill_body_for_mode() (lines 70-85), which retains only content sections explicitly marked for ultra mode or unmarked sections, while discarding content intended for milder modes.

Persistent Configuration Methods

For users who want every new session to start in ultra mode automatically, Ponytail provides two persistent configuration approaches handled by the _default_mode() function (lines 52-64).

Setting the PONYTAIL_DEFAULT_MODE Environment Variable

The simplest persistent method is setting the PONYTAIL_DEFAULT_MODE environment variable. The _default_mode() function checks this variable during plugin initialization before attempting to read any configuration files.

# Add to ~/.bashrc, ~/.zshrc, or Windows System Environment Variables

export PONYTAIL_DEFAULT_MODE=ultra

Creating a config.json Configuration File

Alternatively, create a config.json file in the Ponytail configuration directory. The helper function _config_dir() (lines 44-49) resolves the directory using the XDG_CONFIG_HOME environment variable, Windows APPDATA, or falling back to ~/.config/ponytail.

# Create the config directory (Linux/macOS example)

mkdir -p ~/.config/ponytail

# Create the configuration file

cat > ~/.config/ponytail/config.json <<'EOF'
{
  "defaultMode": "ultra"
}
EOF

When _default_mode() detects this file (lines 57-60), it reads the defaultMode field and applies the specified mode as the global default.

Dynamic Mode Switching with Slash Commands

For ad-hoc mode changes during active sessions without modifying persistent configuration, Ponytail provides slash command functionality implemented in _handle_mode_command (lines 66-78).

Enabling Ultra Mode Temporarily

To switch to ultra mode immediately for the current session only:

/ponytail ultra

The command handler validates the argument against RUNTIME_MODES and stores the selection in the module-level _current_mode variable, overriding any default settings.

Querying the Current Mode

To verify the active mode at any time:

/ponytail

This returns the current state: "Ponytail mode: ultra. Use /ponytail lite|full|ultra|off."

Technical Implementation: How Ultra Mode Filters Content

When ultra mode is active, the build_injected_context() function (lines 105-122 of __init__.py) constructs the injected context by calling _filter_skill_body_for_mode() (lines 70-85). This filter parses skills/ponytail/SKILL.md and strictly retains only content sections explicitly marked for ultra mode or content without mode restrictions, effectively eliminating sections intended for lite or full modes only.

Summary

• Environment Variable: Set PONYTAIL_DEFAULT_MODE=ultra for system-wide defaults that apply on every plugin start.
• Configuration File: Create config.json with "defaultMode": "ultra" in the Ponytail config directory (~/.config/ponytail/ on Unix systems).
• Slash Commands: Use /ponytail ultra for immediate, session-specific mode changes without affecting persistent settings.
• Filtering Logic: Ultra mode invokes _filter_skill_body_for_mode() to restrict injected content to ultra-marked sections of skills/ponytail/SKILL.md.

Frequently Asked Questions

What file paths does Ponytail check for configuration?

Ponytail resolves the configuration directory using _config_dir() in __init__.py, checking XDG_CONFIG_HOME, Windows APPDATA, or defaulting to ~/.config/ponytail. The file config.json must reside in this specific directory to be loaded by _default_mode().

Can I switch from ultra mode back to full or lite mode during a session?

Yes. The slash command /ponytail full or /ponytail lite immediately changes the active mode by updating _current_mode in __init__.py (lines 66-78), overriding any persistent configuration for that session only without modifying your config.json or environment variables.

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

The _default_mode() function (lines 52-64) prioritizes the environment variable PONYTAIL_DEFAULT_MODE first. If that is not set, it falls back to reading the defaultMode value from <config-dir>/config.json. If neither configuration source exists, the plugin uses an internal hardcoded default.

Does ultra mode affect the ponytail-review skill?

Ultra mode specifically filters skills/ponytail/SKILL.md through _filter_skill_body_for_mode(). The skills/ponytail-review/SKILL.md file is used when a separate review configuration mode is selected, which is handled independently from the standard ultra, full, lite, and off runtime modes.

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