# How to Resolve the Active Default Mode in Ponytail Programmatically

> Programmatically resolve the active default mode in Ponytail by calling getDefaultMode() from hooks/ponytail-config.js. Learn how to access environment variables, config files, or fallback constants.

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

---

**Call `getDefaultMode()` exported from [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) to programmatically resolve the active default mode from environment variables, user configuration files, or the hard-coded fallback constant.**

Ponytail determines which runtime mode (`off`, `lite`, `full`, or `ultra`) activates for new sessions through a layered resolution system. Understanding how to programmatically inspect and manipulate this default allows you to customize behavior without interacting with the CLI. This guide covers the resolution hierarchy and practical implementations based on the DietrichGebert/ponytail source code.

## How Ponytail Resolves the Active Default Mode

The resolution logic follows a strict priority chain defined in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js). When resolving the default mode, Ponytail checks three sources in descending order of precedence:

1. **Environment Variable**: `PONYTAIL_DEFAULT_MODE` takes highest priority.
2. **User Configuration File**: A [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) located in the platform-specific config directory (`$XDG_CONFIG_HOME/ponytail`, `~/.config/ponytail`, or `%APPDATA%\ponytail` on Windows).
3. **Hard-Coded Fallback**: The constant `DEFAULT_MODE` (currently set to `"full"`).

The resolver normalizes the retrieved value to one of the four valid runtime modes before returning it.

## The Session Initialization Workflow

When Ponytail initializes a new prompt-handling cycle, the default mode resolution interacts with session storage through a specific orchestration flow:

- **Step 1**: `getDefaultMode()` in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) (lines 76-99) resolves the default using the hierarchy above.
- **Step 2**: `readMode()` in [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) checks whether a session-specific mode already exists.
- **Step 3**: If no session mode exists, `setMode(defaultMode)` in [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) persists the default as the active session mode.
- **Step 4**: `writeHookOutput()` in [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) (lines 96-106) emits the appropriate hook output based on the resolved mode.

## Core API Functions for Mode Resolution

Four primary functions control default mode resolution and persistence:

- **`getDefaultMode()`**: Returns the effective default mode string after evaluating environment variables, config files, and fallbacks.
- **`writeDefaultMode(mode)`**: Persists a new default mode to the user's [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file (lines 36-51 in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)).
- **`readMode()`**: Retrieves the currently active session mode from runtime storage.
- **`setMode(mode)`**: Sets the session-scoped mode without modifying the persistent default configuration.

## Practical Implementation Examples

### Retrieve the Resolved Default Mode

To obtain the default mode that Ponytail will use for a fresh session, import and call `getDefaultMode()`:

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

const defaultMode = getDefaultMode();   // → 'off' | 'lite' | 'full' | 'ultra'
console.log(`Ponytail default mode is: ${defaultMode}`);

```

This implementation references [`ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-config.js) lines 76-99, where the function evaluates `process.env.PONYTAIL_DEFAULT_MODE`, reads the user configuration file, and falls back to the `DEFAULT_MODE` constant.

### Persist a New Default Mode

To permanently change the default mode for future sessions, use `writeDefaultMode()`:

```javascript
const { writeDefaultMode } = require('./hooks/ponytail-config');

const persisted = writeDefaultMode('lite');
if (persisted) {
  console.log('Default mode saved as "lite". New sessions will start in lite.');
}

```

This function writes to the platform-specific configuration directory, ensuring the change persists across terminal sessions.

### Initialize a Session with the Default Mode

To replicate Ponytail's internal behavior of applying the default mode to new sessions, combine the config resolver with runtime session management:

```javascript
const { getDefaultMode } = require('./hooks/ponytail-config');
const { readMode, setMode } = require('./hooks/ponytail-runtime');

// If the session has no mode yet, adopt the default
if (!readMode()) {
  const defaultMode = getDefaultMode();
  if (defaultMode !== 'off') {
    setMode(defaultMode);
    console.log(`Session started in ${defaultMode} mode`);
  } else {
    console.log('Ponytail is off for this session');
  }
}

```

This pattern mirrors the initialization logic found in [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) lines 96-106.

### Override the Default for the Current Session Only

To temporarily switch modes without affecting the persistent default configuration:

```javascript
const { setMode } = require('./hooks/ponytail-runtime');

// Switch to "ultra" for the remainder of this session
setMode('ultra');
console.log('Session mode changed to ultra (not persisted)');

```

This approach changes runtime behavior immediately but leaves the [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file and environment variables untouched.

## Summary

- **Resolution Hierarchy**: Ponytail resolves the active default mode in the order of environment variables → user configuration file → hard-coded `"full"` fallback.
- **Primary Function**: `getDefaultMode()` in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) (lines 76-99) provides the definitive resolved value.
- **Persistence**: Use `writeDefaultMode()` to save preferences to disk, or `setMode()` for temporary session-only changes.
- **Session Integration**: The mode tracker initializes sessions by checking `readMode()` before applying the default via `setMode()` during the prompt-handling cycle.

## Frequently Asked Questions

### What are the valid mode values in Ponytail?

Ponytail supports four runtime modes: `off`, `lite`, `full`, and `ultra`. The resolver automatically normalizes configuration values to one of these strings. Attempting to set an invalid mode typically results in the fallback value being used or the operation being rejected by `writeDefaultMode()`.

### Where does Ponytail store the default mode configuration?

The persistent configuration resides in a [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file located within the platform-specific config directory. On Linux and macOS, this is typically `$XDG_CONFIG_HOME/ponytail` or `~/.config/ponytail`. On Windows, the file is stored in `%APPDATA%\ponytail`.

### How do I temporarily change the mode without affecting the default?

Import `setMode()` from [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) and pass the desired mode string. This updates only the current session's runtime state without writing to the configuration file or modifying environment variables. The change persists until you call `setMode()` again or invoke `clearMode()`.

### What happens if I set an invalid mode in the environment variable?

If `PONYTAIL_DEFAULT_MODE` contains an invalid value, the resolution logic in `getDefaultMode()` falls back to the next available source in the hierarchy. It will check the user configuration file next, and if that is also missing or invalid, it will use the hard-coded `DEFAULT_MODE` constant (`"full"`). The function ensures only valid mode strings are returned to the caller.