How to Configure the Default Ponytail Mode in a Config File

Create a config.json file in your platform-specific configuration directory and set the defaultMode field to a valid runtime mode such as "lite", "full", "off", or "ultra" to persistently control Ponytail's operational intensity.

Ponytail, part of the DietrichGebert/ponytail repository, determines its default operational intensity through a layered configuration resolver implemented in hooks/ponytail-config.js. This system checks environment variables, user-provided JSON configuration files, and built-in defaults in that order. Understanding how to configure the default Ponytail mode via a config file provides persistent control over the agent's behavior without requiring command-line flags for every session.

Configuration File Locations and Resolution Order

Ponytail searches for config.json in platform-specific directories following the XDG Base Directory Specification on Unix systems. The resolver logic in hooks/ponytail-config.js (lines 7-9) implements this platform detection using Node.js path utilities.

On Linux and macOS, the resolver checks these locations in order:

• $XDG_CONFIG_HOME/ponytail/config.json (if the environment variable is set)
• ~/.config/ponytail/config.json (fallback when XDG variable is unset)

On Windows, the resolver uses:

• %APPDATA%\ponytail\config.json

If the configuration file does not exist, the system silently proceeds to the built-in fallback.

Configuring the Default Mode Value

Valid values for the defaultMode field are defined in the RUNTIME_MODES constant on line 18 of hooks/ponytail-config.js. You may configure the default Ponytail mode using these values:

• "off" – Disables Ponytail functionality completely
• "lite" – Reduced computational overhead for resource-constrained environments
• "full" – Standard operational intensity (built-in fallback when no config exists)
• "ultra" – Maximum processing power for intensive workflows

Note that "review" is a session-only mode and cannot be persisted as a default configuration value.

Creating the Configuration File

Create a JSON file at the appropriate path for your operating system:

{
  "defaultMode": "lite",
  "quietStartup": true,
  "hideStatus": false
}

The resolver reads this file using fs.readFileSync (lines 86-94) and parses the JSON to extract the defaultMode value.

Programmatic Configuration with ponytail-config.js

The hooks/ponytail-config.js module exports utility functions for programmatic configuration management, allowing you to read and write settings without manually editing JSON files.

Retrieving the Current Default Mode

Use the getDefaultMode() function to verify the resolved configuration:

const { getDefaultMode } = require('./hooks/ponytail-config');
console.log('Current default mode →', getDefaultMode());
// Output: "lite"

This function executes the full resolution chain: environment variable → config file → built-in fallback.

Persisting Configuration Changes

To write the default mode programmatically, use writeDefaultMode():

const { writeDefaultMode } = require('./hooks/ponytail-config');
writeDefaultMode('ultra');   // Persists "ultra" to the config file

This utility ensures the JSON is properly formatted and written to the correct platform-specific location.

Environment Variable Overrides

The PONYTAIL_DEFAULT_MODE environment variable takes precedence over any config file setting. When getDefaultMode() detects this variable, it returns that value immediately without checking the filesystem.

Set the variable in your shell configuration:

export PONYTAIL_DEFAULT_MODE=off

Or in Windows PowerShell:

$env:PONYTAIL_DEFAULT_MODE = "off"

This override is useful for testing different modes without modifying your persistent configuration.

Validation and Error Handling

The configuration resolver validates that the requested mode exists in RUNTIME_MODES. If the config file is missing, malformed, or contains an invalid mode, the system silently falls back to the next source in the chain, ultimately defaulting to "full".

This fail-safe design ensures that Ponytail remains functional even when configuration files contain syntax errors or are accidentally deleted.

Summary

• Location: Place config.json in $XDG_CONFIG_HOME/ponytail/ (Linux/macOS) or %APPDATA%\ponytail\ (Windows)
• Key: Set the defaultMode field to "off", "lite", "full", or "ultra" to configure the default Ponytail mode
• Override: Use the PONYTAIL_DEFAULT_MODE environment variable for temporary changes that supersede the config file
• API: Use getDefaultMode() and writeDefaultMode() from hooks/ponytail-config.js for programmatic access
• Safety: Invalid or missing configurations gracefully fall back to "full" mode without crashing the application

Frequently Asked Questions

Where does Ponytail look for the config.json file?

Ponytail searches platform-specific directories defined in hooks/ponytail-config.js (lines 7-9). On Linux and macOS, it checks $XDG_CONFIG_HOME/ponytail/config.json first, then falls back to ~/.config/ponytail/config.json. On Windows, it uses %APPDATA%\ponytail\config.json. The resolver automatically creates the directory structure when using writeDefaultMode().

Why can't I set "review" as the default mode?

The "review" mode is session-only by design. The RUNTIME_MODES constant in hooks/ponytail-config.js (line 18) explicitly excludes "review" from persistent configuration because it requires interactive user confirmation that is only appropriate for temporary sessions, not automated startup behavior.

How do I temporarily override the config file without editing it?

Set the PONYTAIL_DEFAULT_MODE environment variable. This variable takes highest precedence in the resolution chain implemented in hooks/ponytail-config.js, overriding any value stored in config.json. This approach is ideal for CI/CD pipelines or testing scenarios where you need a specific mode for a single session.

What happens if my config.json contains invalid JSON?

If fs.readFileSync throws an error due to malformed JSON or missing files, the resolver catches the exception and proceeds to the built-in fallback default of "full". This silent failure mode ensures Ponytail remains operational. You can verify the actual resolved mode by calling getDefaultMode() in a Node.js REPL to confirm which source is active.

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