# How to Configure Ponytail Mode to "full": Environment, Config File, and Session Methods

> Learn how to configure Ponytail mode to full using environment variables, config files, or session methods. Understand Ponytail's mode hierarchy for optimal setup.

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

---

**Set the `PONYTAIL_DEFAULT_MODE` environment variable to `full`, create a [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file with `"defaultMode": "full"` in your platform-specific config directory, or rely on the built-in default—Ponytail resolves the active mode using a strict hierarchy that checks environment variables first, user configuration files second, and falls back to the internal constant last.**

Ponytail is an open-source code optimization tool that trims over-engineered patterns using intensity-based rulesets. When you configure Ponytail mode to `full`, you activate the most aggressive trimming level available in the standard runtime modes. The resolution logic lives in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js), where the system validates and prioritizes configuration sources at startup.

## Understanding the Mode Resolution Hierarchy

Ponytail determines the active mode at runtime using a three-tier priority system implemented in the `getDefaultMode()` function (lines 76–99 in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)). The resolver checks sources in this exact order:

1. **Environment variable** `PONYTAIL_DEFAULT_MODE`
2. **User configuration file** at the platform-specific config path (e.g., `~/.config/ponytail/config.json` or `$XDG_CONFIG_HOME/ponytail/config.json`)
3. **Built-in constant** `DEFAULT_MODE`, defined on line 16 as `'full'`

The resolver only accepts values listed in the `RUNTIME_MODES` array (lines 18–19): `off`, `lite`, `full`, and `ultra`. Invalid values in environment variables or config files are ignored, causing the system to fall back to the next source in the hierarchy.

## Setting Ponytail Mode to "full" Permanently

### Method 1: Environment Variable (Highest Priority)

Setting the environment variable forces `full` mode across all sessions regardless of config file contents. This method is ideal for CI/CD pipelines and containerized environments.

```bash
export PONYTAIL_DEFAULT_MODE=full

```

To verify the resolver detects this setting, run:

```bash
node -e "console.log(require('./hooks/ponytail-config').getDefaultMode())"

```

This outputs `full` if the variable is set correctly. The resolver checks `process.env.PONYTAIL_DEFAULT_MODE` first (line 78) and validates it against `RUNTIME_MODES` before accepting it.

### Method 2: Configuration File (Persistent)

For a permanent, user-specific default, write the mode to Ponytail's configuration file. The `writeDefaultMode()` helper (lines 36–51 in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)) handles file creation, or you can manually create the JSON file:

```bash
mkdir -p ~/.config/ponytail
cat > ~/.config/ponytail/config.json <<'EOF'
{
  "defaultMode": "full"
}
EOF

```

The configuration key must be `defaultMode` (not `mode` or `intensity`). When `getDefaultMode()` executes, it reads this file (lines 86–94) and uses the value only if it matches a valid runtime level. If the file is missing or contains invalid JSON, the resolver seamlessly falls back to the built-in `DEFAULT_MODE`.

## Changing Mode During a Session

To temporarily override the default configuration for a single conversation without modifying environment variables or config files, use the slash command:

```text
/ponytail full

```

This command is handled by the mode-tracker hook ([`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js)), which updates the session's persisted mode and injects the corresponding ruleset into every subsequent LLM turn. To query the current mode without changing it, send:

```text
/ponytail

```

The response displays "Ponytail mode: full" when the full intensity is active.

## Verifying the Active Configuration

After configuration, confirm the mode is correctly resolved using one of these methods:

- **Session check**: Send `/ponytail` in the chat and verify the response states "full"
- **Programmatic check**: Run `getDefaultMode()` from the Node.js REPL as shown in the environment variable section above
- **Status line**: If `PONYTAIL_HIDE_STATUS` is not set, the status line indicator shows the active mode

If you see a different mode than expected, check for conflicting environment variables:

```bash
echo $PONYTAIL_DEFAULT_MODE

```

Or remove lingering config files to force the built-in default:

```bash
rm -f ~/.config/ponytail/config.json
unset PONYTAIL_DEFAULT_MODE

```

## Summary

- **Ponytail mode to `full`** is resolved via a strict hierarchy: environment variable → config file → built-in default
- **Environment variable** `PONYTAIL_DEFAULT_MODE=full` takes highest priority and overrides all other settings
- **Config file** location is platform-specific (typically `~/.config/ponytail/config.json`) and uses the key `defaultMode`
- **Built-in fallback** is defined in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) line 16 as `const DEFAULT_MODE = 'full'`, meaning `full` is the default if no overrides exist
- **Session commands** (`/ponytail full`) override defaults for the current conversation only
- **Review mode** (`review`) cannot be set as a default; it is session-only and filtered out by the resolver (line 80)

## Frequently Asked Questions

### What is the difference between "full" and "ultra" mode in Ponytail?

Both are valid runtime levels defined in `RUNTIME_MODES`, but `full` represents the standard maximum intensity while `ultra` applies even more aggressive trimming rules. The `full` mode is the built-in default constant (`DEFAULT_MODE`), making it the recommended baseline for aggressive optimization. `ultra` may remove patterns that `full` preserves, so use it only when you want the most extreme reduction in code complexity.

### Why does my Ponytail mode reset to "lite" when I restart?

This indicates a configuration source is setting `lite` explicitly. Check your shell profile for `export PONYTAIL_DEFAULT_MODE=lite` or inspect the config file at `~/.config/ponytail/config.json`. The resolver prioritizes environment variables over the built-in default of `full`, so any lingering `PONYTAIL_DEFAULT_MODE` definition will override your intended setting. Clear the variable with `unset PONYTAIL_DEFAULT_MODE` and delete the config file to restore the default `full` behavior.

### Can I set the "review" mode as my default?

No, the `review` mode is session-only and cannot be configured as a permanent default. The resolver in `getDefaultMode()` explicitly filters out `review` during validation (see the comment at line 80). This mode is designed for temporary, one-time code reviews rather than ongoing optimization, so it must be activated per-session using `/ponytail review`.

### How do I completely deactivate Ponytail?

Set the mode to `off` using any configuration method: `export PONYTAIL_DEFAULT_MODE=off`, set `"defaultMode": "off"` in [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json), or send `/ponytail off` during a session. The `off` value is a valid entry in `RUNTIME_MODES` that disables all trimming rules. Alternatively, standalone deactivation commands like `stop ponytail` or `normal mode` trigger the `isDeactivationCommand` function (lines 40–43) to disable Ponytail for that specific message context.