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

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, 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:

• 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. The resolver checks sources in the following order, with the first found value winning:

1. Environment variables (highest priority)
2. 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.

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 read these values first before checking the configuration file.

Via the Configuration File

For persistent settings, create or edit 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:

{
  "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 and invokes writeDefaultMode() in hooks/ponytail-config.js (lines 136-150), which validates that the mode is one of the runtime modes (off, lite, full, ultra) before writing.

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:

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 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, which overrides built-in defaults ("full", false, false).
• Configuration file location: Determined by getConfigPath() in hooks/ponytail-config.js (lines 54-68), using 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 at a path constructed by getConfigPath() in 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 (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. For example, running export PONYTAIL_DEFAULT_MODE=lite in your shell overrides the persisted setting for that session only.

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