Where Is Ponytail's Configuration File Stored? A Complete Guide to Config Locations

Ponytail stores its configuration in a JSON file named config.json located inside a platform-specific configuration directory that defaults to $HOME/.config/ponytail/ on Linux/macOS or %APPDATA%\ponytail\ on Windows.

The open-source Ponytail project (available at DietrichGebert/ponytail) persists user settings—such as the default mode, quiet-startup flag, and hidden-status—through a centralized configuration file. Knowing exactly where Ponytail's configuration file resides allows you to manually edit preferences, migrate settings between machines, or troubleshoot environment-specific issues.

Default Configuration File Locations by Platform

Ponytail follows platform conventions for determining where to place its config.json file. The resolution logic in hooks/ponytail-config.js checks environment variables and operating system identifiers to select the appropriate parent directory.

Linux and macOS (Default)

On Unix-like systems without the XDG_CONFIG_HOME environment variable set, Ponytail creates and uses:

$HOME/.config/ponytail/config.json

This aligns with the XDG Base Directory Specification, keeping user-specific application data out of the home directory clutter.

Windows

When process.platform === 'win32' is detected, Ponytail resolves the configuration path using the %APPDATA% environment variable (falling back to %USERPROFILE%\AppData\Roaming if unavailable):

%APPDATA%\ponytail\config.json

XDG Base Directory Compliance

If the XDG_CONFIG_HOME environment variable is explicitly set, Ponytail respects this override and stores the file at:

$XDG_CONFIG_HOME/ponytail/config.json

This behavior is implemented in the getConfigDir() function (lines 55‑64 of hooks/ponytail-config.js), which constructs the directory path before getConfigPath() (line 68) appends the filename.

How Ponytail Resolves the Configuration Path

According to the Ponytail source code, the configuration resolution relies on two core functions exported from hooks/ponytail-config.js:

• getConfigDir() (lines 55‑64): Determines the platform-appropriate base directory
• getConfigPath() (line 68): Concatenates the directory with the filename config.json

When you invoke configuration methods, Ponytail automatically creates the directory structure if it does not exist. The writeDefaultMode implementation (lines 41‑44) demonstrates this behavior, ensuring the path is available before writing JSON data.

Reading and Writing Configuration Values

You can interact with Ponytail's configuration programmatically using the exported helper functions. Below are practical examples for locating, reading, and updating the config.json file.

Retrieve the Configuration File Path

const { getConfigPath } = require('./hooks/ponytail-config');

console.log('Config file is at:', getConfigPath());
// Output: /home/user/.config/ponytail/config.json

Read the Current Default Mode

The getDefaultMode() function reads from the configuration file, falling back to environment variables, and finally defaulting to "full" if no value is set:

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

console.log('Current default mode:', getDefaultMode());

Persist Configuration Changes

To write a new default mode (or other supported settings) to config.json, use writeDefaultMode():

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

writeDefaultMode('ultra');
// Result: config.json now contains {"defaultMode":"ultra"}

This method automatically creates the ponytail subdirectory and the config.json file if they are missing.

Key Source Files for Configuration Logic

Understanding the implementation details requires examining these specific files in the repository:

• hooks/ponytail-config.js: Contains the core resolution logic, including getConfigDir(), getConfigPath(), and the read/write implementations for config.json.
• tests/hooks.test.js: Provides test coverage verifying correct directory resolution and file handling across platforms.
• scripts/uninstall.js: Demonstrates how the configuration file and directory are removed during uninstallation, referencing the same path resolution logic.

Summary

• Ponytail's configuration file is always named config.json and resides in a platform-specific directory.
• Default locations: $HOME/.config/ponytail/config.json (Linux/macOS), %APPDATA%\ponytail\config.json (Windows), or $XDG_CONFIG_HOME/ponytail/config.json when the XDG variable is set.
• Resolution functions: getConfigDir() (lines 55‑64) and getConfigPath() (line 68) in hooks/ponytail-config.js handle path construction.
• Auto-creation: The directory structure is created automatically when writing configuration values via functions like writeDefaultMode() (lines 41‑44).
• Programmatic access: Use getConfigPath(), getDefaultMode(), and writeDefaultMode() to interact with settings without manually editing the file.

Frequently Asked Questions

What is the exact filename for Ponytail's configuration?

The file is always named config.json. It is stored inside the platform-specific configuration directory resolved by getConfigDir() in hooks/ponytail-config.js.

Can I move Ponytail's configuration file to a custom location?

Ponytail does not currently support arbitrary custom paths via command-line flags. However, on Linux and macOS, you can override the parent directory by setting the XDG_CONFIG_HOME environment variable, which causes Ponytail to place its ponytail/config.json subdirectory inside your specified path instead of the default $HOME/.config.

Does Ponytail create the configuration directory automatically?

Yes. When you call writeDefaultMode() or any function that persists settings, Ponytail checks for the existence of the configuration directory and creates it recursively if missing. This behavior is defined in lines 41‑44 of hooks/ponytail-config.js.

How does the configuration path differ between Windows and Linux?

On Windows, Ponytail uses the %APPDATA% environment variable (typically resolving to C:\Users\<Username>\AppData\Roaming), resulting in %APPDATA%\ponytail\config.json. On Linux and macOS, it defaults to $HOME/.config/ponytail/config.json unless XDG_CONFIG_HOME is defined.

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