# How to Change the Default Ponytail Mode: Environment Variables, Config Files, and Commands

> Discover how to change the default Ponytail mode using environment variables, config files, or commands. Learn the priority chain for setting your preferred intensity.

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

---

**Ponytail determines its default intensity level through a three-step priority chain: first checking the `PONYTAIL_DEFAULT_MODE` environment variable, then falling back to the `defaultMode` field in [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json), and finally defaulting to `full` if neither is set.**

In the DietrichGebert/ponytail repository, the default mode dictates which intensity level (off, lite, full, or ultra) activates automatically when you start a new session. Understanding how to change the default Ponytail mode allows you to customize the tool's behavior permanently without passing flags to every invocation.

## Understanding the Priority Chain

Ponytail resolves the default mode using a strict hierarchy implemented in [[`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js). The `getDefaultMode()` function evaluates three sources in order:

1. **Environment variable** `PONYTAIL_DEFAULT_MODE` — highest precedence
2. **User configuration file** [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) — located in the platform-specific config directory
3. **Built-in constant** `DEFAULT_MODE` — hardcoded to `'full'`

Only runtime modes (`off`, `lite`, `full`, `ultra`) are valid defaults. The `review` mode is session-only and cannot be set as a permanent default.

## Method 1: Set the Environment Variable

Setting the environment variable provides the fastest way to change the default Ponytail mode and overrides any configuration file settings. This variable is read each time Ponytail initializes.

For Bash or Zsh:

```bash
export PONYTAIL_DEFAULT_MODE=lite

```

For Windows Command Prompt:

```cmd
set PONYTAIL_DEFAULT_MODE=ultra

```

For PowerShell:

```powershell
$env:PONYTAIL_DEFAULT_MODE = "off"

```

## Method 2: Edit the Configuration File

For persistent changes that persist across shell sessions, modify the [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file. The `writeDefaultMode()` function in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) handles validation and I/O operations for this file.

Locate your configuration directory based on your operating system:

- **Linux/macOS**: `~/.config/ponytail/config.json` (or `$XDG_CONFIG_HOME/ponytail/config.json` if set)
- **Windows**: `%APPDATA%\ponytail\config.json`

Create or edit the file with the following structure:

```json
{
  "defaultMode": "ultra",
  "quietStartup": true,
  "hideStatus": false
}

```

Ponytail validates that the `defaultMode` value matches one of the allowed runtime intensities before applying it.

## Method 3: Use the /ponytail default Command

When running Ponytail within a compatible host environment (such as the Pi extension), you can change the default mode conversationally. The command handler in [[`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js)](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) invokes `writeDefaultMode()` to update [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) directly.

Example usage:

```

/ponytail default lite

```

This method performs the same validation as manual file editing and immediately affects subsequent sessions.

## Validating Your Current Default

To verify which mode Ponytail will use for the next session, inspect the resolved default programmatically:

```javascript
const { getDefaultMode } = require("./hooks/ponytail-config.js");

console.log("Current default mode:", getDefaultMode());
// Output: "lite", "full", "ultra", or "off" depending on your configuration

```

You can also programmatically set the default from a Node.js script:

```javascript
const { writeDefaultMode, getDefaultMode } = require("./hooks/ponytail-config.js");

writeDefaultMode("ultra");
console.log("Updated default:", getDefaultMode());

```

The [[`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) file activates this default value on the first prompt when no session flag file exists, ensuring your preference applies immediately.

## Summary

- **Highest priority**: Set the `PONYTAIL_DEFAULT_MODE` environment variable for immediate, session-specific overrides.
- **Persistent storage**: Edit [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) in your platform's configuration directory (`~/.config/ponytail/` on Unix, `%APPDATA%\ponytail\` on Windows).
- **Interactive change**: Use `/ponytail default <mode>` in supported host environments to invoke `writeDefaultMode()`.
- **Fallback behavior**: If no configuration exists, Ponytail defaults to `full` intensity as defined in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).

## Frequently Asked Questions

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

No. The `review` mode is session-only and excluded from the validation logic in `getDefaultMode()`. Only `off`, `lite`, `full`, and `ultra` are valid values for the default configuration.

### Where exactly is the configuration file located on my system?

Ponytail searches for [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) using platform-specific logic. On Linux and macOS, it checks `$XDG_CONFIG_HOME/ponytail/` first, then falls back to `~/.config/ponytail/`. On Windows, it uses `%APPDATA%\ponytail\`. The file must contain a JSON object with a `defaultMode` string field.

### Does the environment variable override an existing config file?

Yes. The resolution chain in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) checks `process.env.PONYTAIL_DEFAULT_MODE` before reading the filesystem. If the environment variable is present and valid, Ponytail skips the configuration file entirely and uses that value.

### What happens if I specify an invalid mode in the config file?

The `writeDefaultMode()` function validates inputs against the allowed set of runtime modes. If you manually edit [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) with an invalid value (such as `"aggressive"` or `"review"`), `getDefaultMode()` will ignore it and fall back to the built-in `full` default.