How to Resolve the Active Default Mode in Ponytail Programmatically

Call getDefaultMode() exported from 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. 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 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 (lines 76-99) resolves the default using the hierarchy above.
• Step 2: readMode() in 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 persists the default as the active session mode.
• Step 4: writeHookOutput() in 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 file (lines 36-51 in 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():

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

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:

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 lines 96-106.

Override the Default for the Current Session Only

To temporarily switch modes without affecting the persistent default configuration:

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 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 (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 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 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.

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