# How to Configure the Default Ponytail Mode in a Config File

> Configure the default Ponytail mode by creating a config.json file and setting the defaultMode field to lite, full, off, or ultra. Control Ponytail's operational intensity persistently.

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

---

**Create a [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) in platform-specific directories following the **XDG Base Directory Specification** on Unix systems. The resolver logic in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```json
{
  "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`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```js
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()`:

```js
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:

```bash
export PONYTAIL_DEFAULT_MODE=off

```

Or in Windows PowerShell:

```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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js), overriding any value stored in [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/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.