How to Configure Ponytail Mode to Lite: 3 Configuration Methods

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 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 (lines 52-55), Ponytail reads this variable at startup and uses it as the default when no explicit mode is supplied via runtime commands.

export PONYTAIL_DEFAULT_MODE=lite

On Windows systems, use the equivalent command:

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) attempts to read the defaultMode key from this file:

{
  "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) 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:

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). 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:

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 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, lines 52-55).
• Configuration file: Create ${XDG_CONFIG_HOME}/ponytail/config.json containing "defaultMode": "lite" for persistent settings (referenced in __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, 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 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 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) 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) 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.

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