# Ponytail Configuration Options: Environment Variables, Config File, and CLI Setup

> Explore Ponytail configuration options: environment variables, config file, and CLI setup. Learn how to set defaultMode quietStartup and hideStatus for optimal control. Environment variables have precedence.

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

---

**Ponytail provides three configuration options—`defaultMode`, `quietStartup`, and `hideStatus`—that can be set via environment variables, a JSON config file at [`XDG_CONFIG_HOME/ponytail/config.json`](https://github.com/DietrichGebert/ponytail/blob/main/XDG_CONFIG_HOME/ponytail/config.json), or the `/ponytail default <mode>` CLI command, with environment variables taking precedence.**

Ponytail is an open-source coding assistant that exposes user-controllable settings through a layered configuration system. Understanding the available Ponytail configuration options allows you to customize runtime intensity, suppress startup notifications, and manage status-line visibility without modifying source code in `DietrichGebert/ponytail`.

## Available Configuration Options

Ponytail exposes three primary settings controlled through [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js):

- **defaultMode**: Determines the runtime intensity. Valid values are `"off"`, `"lite"`, `"full"`, and `"ultra"`. The special `"review"` mode is valid for temporary use but cannot be persisted as a default.
- **quietStartup**: When `true`, suppresses the "Ponytail loaded" toast notification while keeping the extension active. Defaults to `false`.
- **hideStatus**: When `true`, hides the status-line indicator while leaving Ponytail running in the background. Defaults to `false`.

## Configuration Resolution and Precedence

According to the `DietrichGebert/ponytail` source code, configuration values are resolved using a strict three-tier precedence system implemented in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js). The resolver checks sources in the following order, with the first found value winning:

1. **Environment variables** (highest priority)
2. **[`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file** at the path determined by `getConfigPath()` (lines 54-68)
3. **Built-in defaults** (lowest priority)

The `getDefaultMode()` function (lines 76-99) checks `PONYTAIL_DEFAULT_MODE` first, then the JSON file, and finally falls back to `"full"`. Similarly, `getQuietStartup()` (lines 101-117) and `getHideStatus()` (lines 119-133) follow this pattern for their respective environment variables.

## How to Set Ponytail Configuration Options

### Via Environment Variables

Export variables before launching your editor to override file-based configuration. This method is ideal for temporary or session-specific changes.

```bash
export PONYTAIL_DEFAULT_MODE=lite
export PONYTAIL_QUIET_STARTUP=1
export PONYTAIL_HIDE_STATUS=1

```

Environment variables take precedence over all other configuration sources. The resolver functions in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) read these values first before checking the configuration file.

### Via the Configuration File

For persistent settings, create or edit [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) at the location returned by `getConfigPath()`. By default, this resolves to `$XDG_CONFIG_HOME/ponytail/config.json` on Linux, with platform-specific fallbacks for macOS and Windows.

Example configuration:

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

```

The file is automatically created when you persist settings via CLI commands.

### Via CLI Commands

Ponytail provides the `/ponytail default <mode>` command to persist the default mode to the configuration file. This command is handled by [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) and invokes `writeDefaultMode()` in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) (lines 136-150), which validates that the mode is one of the runtime modes (`off`, `lite`, `full`, `ultra`) before writing.

```bash
ponytail default ultra

```

Attempts to store the special `"review"` mode via this command are ignored by the validation logic.

## Programmatic Access to Configuration

For extension developers consuming Ponytail settings, import the resolver functions:

```javascript
const { getDefaultMode, getQuietStartup, getHideStatus } = require('./hooks/ponytail-config');

const mode = getDefaultMode();          // → 'full' | 'lite' | 'ultra' | ...
const silent = getQuietStartup();       // → boolean
const hidden = getHideStatus();         // → boolean

```

The file [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) demonstrates practical consumption of these configuration values.

## Summary

- **Three options control Ponytail**: `defaultMode` (runtime intensity), `quietStartup` (suppress toast), and `hideStatus` (hide indicator).
- **Resolution order**: Environment variables override [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json), which overrides built-in defaults (`"full"`, `false`, `false`).
- **Configuration file location**: Determined by `getConfigPath()` in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) (lines 54-68), using [`XDG_CONFIG_HOME/ponytail/config.json`](https://github.com/DietrichGebert/ponytail/blob/main/XDG_CONFIG_HOME/ponytail/config.json) with platform fallbacks.
- **CLI persistence**: Use `/ponytail default <mode>` to write valid runtime modes to the config file via `writeDefaultMode()` (lines 136-150).
- **Review mode limitation**: The `"review"` mode cannot be persisted as a default through any configuration mechanism.

## Frequently Asked Questions

### What are the valid values for defaultMode in Ponytail?

The `defaultMode` configuration option accepts four runtime values: `"off"`, `"lite"`, `"full"`, and `"ultra"`. These determine the AI processing intensity. The special `"review"` mode exists for temporary activation but cannot be persisted as a default in the configuration file or via CLI commands.

### Where is the Ponytail configuration file located?

Ponytail stores configuration in [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) at a path constructed by `getConfigPath()` in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js). By default, this resolves to `$XDG_CONFIG_HOME/ponytail/config.json` on Linux, with macOS and Windows fallbacks following platform-specific conventions. The file is created automatically when you run persistence commands like `/ponytail default`.

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

No. While `"review"` is a valid operational mode for temporary use, it cannot be persisted as the `defaultMode`. The `writeDefaultMode()` function in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) (lines 136-150) explicitly ignores attempts to store `"review"` in the configuration file. You must activate review mode manually per session.

### How do I temporarily override a Ponytail setting without changing the config file?

Set the corresponding environment variable before launching your editor. `PONYTAIL_DEFAULT_MODE`, `PONYTAIL_QUIET_STARTUP`, and `PONYTAIL_HIDE_STATUS` take precedence over file-based configuration according to the resolver logic in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js). For example, running `export PONYTAIL_DEFAULT_MODE=lite` in your shell overrides the persisted setting for that session only.