# How to Configure Ponytail Mode to Ultra: 3 Methods Explained

> Learn how to configure Ponytail mode to ultra using environment variables, config files, or slash commands. Enhance your content filtering today!

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

---

**To configure Ponytail mode to `ultra`, set the `PONYTAIL_DEFAULT_MODE` environment variable to `ultra`, create a [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/__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.

```bash

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

```bash

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

```python
/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:

```python
/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`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py)) constructs the injected context by calling `_filter_skill_body_for_mode()` (lines 70-85). This filter parses [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py), checking `XDG_CONFIG_HOME`, Windows `APPDATA`, or defaulting to `~/.config/ponytail`. The file [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py) (lines 66-78), overriding any persistent configuration for that session only without modifying your [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md) through `_filter_skill_body_for_mode()`. The [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/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.