# How to Configure Ponytail Mode to Lite: 3 Configuration Methods

> Easily configure Ponytail mode to lite using environment variables, config files, or slash commands. Learn the simple steps to activate minimal assistance in the DietrichGebert/ponytail repository.

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

---

**Set the `PONYTAIL_DEFAULT_MODE` environment variable to `lite`, add `"defaultMode": "lite"` to your Ponytail config file, or send the `/ponytail lite` slash command to activate the minimal assistance level.**

Ponytail is an open-source context injection system developed by DietrichGebert that implements "lazy senior dev" logic for LLM interactions. When you configure Ponytail mode to lite, the system reduces the amount of guidance injected into prompts, keeping token usage minimal while still applying architectural oversight. This configuration controls which sections of the skill instructions are filtered by `_filter_skill_body_for_mode()` in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py) before reaching the LLM.

## Method 1: Environment Variable Configuration

The most script-friendly way to configure Ponytail mode to lite is through the `PONYTAIL_DEFAULT_MODE` environment variable. According to the source code in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py) (lines 52-55), Ponytail reads this variable at startup and uses it as the default when no explicit mode is supplied via runtime commands.

```bash
export PONYTAIL_DEFAULT_MODE=lite

```

On Windows systems, use the equivalent command:

```cmd
set PONYTAIL_DEFAULT_MODE=lite

```

When the process starts, the `_default_mode()` function normalizes the value through `_normalize_config_mode()` (lines 37-41) to ensure it matches the allowed set `{"off", "lite", "full", "ultra"}` before storing it as the effective mode.

## Method 2: User Config File Configuration

If the environment variable is absent, Ponytail falls back to a JSON configuration file located at `${XDG_CONFIG_HOME}/ponytail/config.json` (using platform-specific fallbacks when XDG variables are unset). The `_default_mode()` function implementation (lines 56-60 in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py)) attempts to read the `defaultMode` key from this file:

```json
{
  "defaultMode": "lite"
}

```

Create this file and directory structure if they do not exist. The configuration file method persists your preference across terminal sessions without requiring shell profile modifications.

## Method 3: Runtime Slash Command

For per-session changes without restarting your LLM client, use the Hermes gateway slash command. When you type `/ponytail lite` in a supported chat interface, the gateway rewrites this command via `rewrite_gateway_command()` and invokes `_handle_mode_command()` (lines 67-77 in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py)) to update the in-memory `_current_mode` variable immediately.

```

/ponytail lite

```

The system responds by confirming the mode change, and all subsequent LLM turns in that session will use the lite context filtering. You can verify the active mode programmatically:

```python
from ponytail import _current_mode, _default_mode
print("Current runtime mode:", _current_mode or _default_mode())

# Output: lite

```

## How Mode Filtering Works

Once configured to lite, the technical implementation flows through `build_injected_context()` (lines 5-22 in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py)). This function determines the effective mode by calling `_default_mode()`, normalizes it via `_normalize_runtime_mode()` (lines 30-34), and filters the skill body accordingly:

```python
effective = _normalize_runtime_mode(mode) or DEFAULT_MODE
body = PONYTAIL_SKILL.read_text()
return _filter_skill_body_for_mode(body, effective)

```

The `_filter_skill_body_for_mode()` function (lines 70-86) parses [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md) and discards sections marked for different modes (such as `full` or `ultra`), returning only the instructions relevant to lite mode. If the skill file cannot be read, the system safely falls back to `_fallback_instructions` (lines 90-102) while still indicating the active mode in the context.

## Summary

- **Environment variable**: Export `PONYTAIL_DEFAULT_MODE=lite` before launching your LLM client to set the default mode at startup (referenced in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py), lines 52-55).
- **Configuration file**: Create `${XDG_CONFIG_HOME}/ponytail/config.json` containing `"defaultMode": "lite"` for persistent settings (referenced in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py), lines 56-60).
- **Runtime command**: Use `/ponytail lite` in supported chat sessions to update `_current_mode` without process restarts (referenced in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py), lines 67-77).
- **Validation**: All mode inputs pass through `_normalize_runtime_mode()` or `_normalize_config_mode()` to enforce the allowed values: `off`, `lite`, `full`, or `ultra`.
- **Context injection**: The active mode determines which sections of [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md) are included in the prompt prefix via `_filter_skill_body_for_mode()`.

## Frequently Asked Questions

### What is the difference between lite, full, and ultra modes in Ponytail?

Lite mode provides minimal "lazy senior dev" guidance to keep prompts concise and token-efficient. Full mode includes comprehensive architectural oversight and detailed review criteria. Ultra mode adds aggressive optimization suggestions and advanced refactoring patterns. All three modes operate on the same underlying skill file, but `_filter_skill_body_for_mode()` includes different markdown sections based on the active mode setting.

### Where does Ponytail store its configuration file?

Ponytail follows the XDG Base Directory specification, looking for [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) in `${XDG_CONFIG_HOME}/ponytail/` on Unix systems. On Windows or macOS, it uses platform-specific fallback directories. The `_default_mode()` function checks this location (lines 56-60 in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py)) only when the `PONYTAIL_DEFAULT_MODE` environment variable is not present.

### Can I change Ponytail modes without restarting my LLM client?

Yes. Use the `/ponytail lite` slash command in any chat session supported by the Hermes gateway. The `_handle_mode_command()` function (lines 67-77 in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py)) updates the global `_current_mode` variable immediately, and subsequent prompts in that session will use the filtered lite context without requiring a client restart.

### What happens if I set an invalid mode name in Ponytail?

Invalid modes are sanitized by normalization functions. `_normalize_runtime_mode()` (lines 30-34) and `_normalize_config_mode()` (lines 37-41) validate inputs against the allowed set `{"off", "lite", "full", "ultra"}`. If an invalid value is provided, these functions return `None`, causing the system to fall back to the next available configuration source or a safe default, ensuring the LLM always receives valid context instructions.