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

> Discover where Ponytail's config json file is stored. Learn about platform-specific locations for Linux, macOS, and Windows to manage your settings easily.

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

---

**Ponytail stores its configuration in a JSON file named [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file. The resolution logic in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```text
$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):

```text
%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:

```text
$XDG_CONFIG_HOME/ponytail/config.json

```

This behavior is implemented in the `getConfigDir()` function (lines 55‑64 of [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) file.

### Retrieve the Configuration File Path

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

```javascript
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`](https://github.com/DietrichGebert/ponytail/blob/main/config.json), use `writeDefaultMode()`:

```javascript
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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)**: Contains the core resolution logic, including `getConfigDir()`, `getConfigPath()`, and the read/write implementations for [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json).
- **[`tests/hooks.test.js`](https://github.com/DietrichGebert/ponytail/blob/main/tests/hooks.test.js)**: Provides test coverage verifying correct directory resolution and file handling across platforms.
- **[`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/config.json)**. It is stored inside the platform-specific configuration directory resolved by `getConfigDir()` in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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.