# How to Set the Default Ponytail Mode for New Sessions Using Environment Variables

> Easily set the default Ponytail mode for new sessions by configuring the PONYTAIL_DEFAULT_MODE environment variable. Learn how to control your session behavior effortlessly.

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

---

**Set the `PONYTAIL_DEFAULT_MODE` environment variable to one of the valid modes (`off`, `lite`, `full`, `ultra`, or `review`) before launching your session, and Ponytail will automatically use that value as the default operating mode for all new contexts.**

The DietrichGebert/ponytail repository provides a hierarchical configuration system that determines how much skill context is injected into LLM prompts. By setting an environment variable, you can globally control this behavior without modifying source code or passing arguments to every function call.

## Understanding Ponytail's Configuration Hierarchy

Ponytail resolves the active mode through a strict precedence chain implemented in [`ponytail/main/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/main/__init__.py):

1. **Explicit argument** – The `mode` parameter passed directly to `build_injected_context(mode)`
2. **Environment variable** – The value of `PONYTAIL_DEFAULT_MODE`
3. **Configuration file** – The `defaultMode` key in a JSON config file
4. **Built-in fallback** – The constant `DEFAULT_MODE = "full"` (defined at line 11)

The environment variable serves as the primary mechanism for establishing persistent defaults across sessions, sitting just below explicit runtime overrides.

## Setting the PONYTAIL_DEFAULT_MODE Environment Variable

Configure the variable in your shell or CI/CD environment before invoking any Ponytail commands.

### Linux and macOS (Bash/Zsh)

Set the variable for your entire session:

```bash
export PONYTAIL_DEFAULT_MODE=lite
ponytail run your_script.py

```

Set it for a single command execution:

```bash
PONYTAIL_DEFAULT_MODE=ultra ponytail run your_script.py

```

### Windows PowerShell

```powershell
$env:PONYTAIL_DEFAULT_MODE = "full"
ponytail run your_script.py

```

### Windows Command Prompt (CMD)

```cmd
set PONYTAIL_DEFAULT_MODE=lite
ponytail run your_script.py

```

## How Ponytail Processes the Environment Variable

During session initialization, the `_default_mode()` function in [`ponytail/main/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/main/__init__.py) retrieves and validates the environment variable. The code explicitly reads:

```python
env_mode = _normalize_config_mode(os.environ.get("PONYTAIL_DEFAULT_MODE"))

```

The normalization logic (around line 40) handles validation through the `_normalize_config_mode()` function:

```python
def _normalize_config_mode(mode: str | None) -> str | None:
    if not isinstance(mode, str):
        return None
    mode = mode.strip().lower()
    return mode if mode in CONFIG_MODES else None

```

This ensures the value is case-insensitive and whitespace-tolerant. If the normalized string exists in `CONFIG_MODES`, it becomes the effective mode for the session; otherwise, Ponytail proceeds to check the configuration file or falls back to `"full"`.

## Valid Mode Values

The `PONYTAIL_DEFAULT_MODE` environment variable accepts the following string values:

- **`off`** – Disables context injection entirely
- **`lite`** – Enables minimal context for reduced latency
- **`full`** – Standard context level (built-in fallback default)
- **`ultra`** – Maximum context injection for complex tasks
- **`review`** – Specialized mode for code review contexts

The validation set `CONFIG_MODES` contains these options, allowing the `_normalize_config_mode()` filter to accept any case variation (e.g., `LITE`, `Lite`, and `lite` are equivalent).

## Overriding the Default Mode at Runtime

Even with `PONYTAIL_DEFAULT_MODE` configured in your environment, you can force a specific mode for individual calls by passing the `mode` argument to `build_injected_context()`:

```python
from ponytail import build_injected_context

# Explicitly forces 'ultra' mode, bypassing the environment variable

ctx = build_injected_context(mode="ultra")

```

This explicit parameter takes precedence over all other configuration sources, including the environment variable and configuration files.

## Cross-Platform JavaScript Support

For browser or Node.js runtimes, Ponytail reads the same environment variable through [`ponytail/main/hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/main/hooks/ponytail-config.js). This ensures consistent behavior between Python backends and JavaScript frontends when the variable is set at the system level.

## Summary

- **Set** `PONYTAIL_DEFAULT_MODE` to `off`, `lite`, `full`, `ultra`, or `review` to control default session behavior
- **Precedence order**: Explicit argument → Environment variable → Config file → `"full"` fallback
- **Implementation**: Core logic resides in [`ponytail/main/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/main/__init__.py) via `_default_mode()` and `_normalize_config_mode()`
- **Case handling**: Values are normalized with `.strip().lower()`, making them case-insensitive
- **Override**: Use `build_injected_context(mode="...")` to bypass the environment default for specific calls

## Frequently Asked Questions

### What happens if I don't set the PONYTAIL_DEFAULT_MODE environment variable?

If the environment variable is undefined, empty, or contains an invalid value, Ponytail proceeds to check the configuration file for a `defaultMode` key. If that is also absent, it falls back to the built-in constant `DEFAULT_MODE = "full"` defined in [`ponytail/main/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/main/__init__.py).

### Is the environment variable case-sensitive?

No. The `_normalize_config_mode()` function in [`ponytail/main/__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail/main/__init__.py) explicitly converts the input to lowercase using `.lower()` and trims whitespace with `.strip()`. Therefore, `FULL`, `Full`, and `full` are all treated identically.

### Can I set the default mode in a configuration file instead of using environment variables?

Yes. Ponytail supports JSON configuration files where you can specify a `"defaultMode"` key. However, the configuration hierarchy places environment variables above file settings, meaning `PONYTAIL_DEFAULT_MODE` will override any value defined in the configuration file if both are present.

### How do I verify which mode is currently active?

You can programmatically inspect the resolved mode by calling `_default_mode()` after importing from the package:

```python
import os
from ponytail import _default_mode

os.environ["PONYTAIL_DEFAULT_MODE"] = "lite"
print(_default_mode())  # Output: lite

```

Additionally, Ponyltail injects a banner into the generated context (via `_fallback_instructions()`) that indicates the active mode level, making it visible in the final prompt passed to the LLM.