# How to Customize Ponytail's Behavior: Environment Variables, Config Files, and Custom Skills

> Customize Ponytail's behavior using environment variables config files and custom skills. Learn how to tailor its functionality for your specific needs.

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

---

**You can customize Ponytail's behavior through three layers—mode intensity, runtime UI flags, and skill extensions—controlled via environment variables, a JSON config file, or the built-in `/ponytail` command.**

Ponytail is an open-source AI coding assistant plugin designed to enforce a "lazy senior dev" approach to code generation. Whether you need to dial back the intensity for legacy projects or extend the tool with custom audit rules, the repository at `DietrichGebert/ponytail` provides deterministic configuration resolution that works across all supported hosts including Claude, Codex, Gemini, and Qoder.

## Understanding Ponytail's Configuration Architecture

Ponytail combines three distinct customization layers at runtime:

- **Mode intensity** (`off`, `lite`, `full`, `ultra`) – Controls how aggressively the lazy senior dev ladder is applied
- **Runtime configuration** – Quiet startup, status-line hiding, and shell-safe path handling  
- **Skill/command extensions** – Adding, removing, or overriding the built-in `/ponytail*` commands

The resolution logic resides in [[`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js), while skill declarations live in [[`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml)](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml) and the `skills/` directory.

## Setting the Default Mode

The `getDefaultMode()` function in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) (lines 4-11) resolves the active mode through a strict priority chain:

1. **`PONYTAIL_DEFAULT_MODE`** environment variable (highest priority)
2. **`~/.config/ponytail/config.json`** (or XDG/Windows equivalents)
3. **Hard-coded fallback** to `"full"`

```javascript
// From hooks/ponytail-config.js lines 4-11
const envMode = process.env.PONYTAIL_DEFAULT_MODE;
if (envMode && RUNTIME_MODES.includes(envMode.toLowerCase())) {
  return envMode.toLowerCase();
}

// Falls through to config file, then DEFAULT_MODE constant

```

Only runtime levels (`off`, `lite`, `full`, `ultra`) can be persisted. The session-only `review` mode cannot be set as a default (lines 78-84 guard against this).

To set a persistent default, create or edit the config file located via `getConfigPath()` (lines 54-69):

```json
{
  "defaultMode": "lite",
  "quietStartup": true,
  "hideStatus": false
}

```

## Switching Modes at Runtime

You can override the default mode temporarily using the built-in command **`/ponytail [lite|full|ultra|off]`**, defined in [[`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml#L1-L3):

```toml
description = "Switch ponytail intensity level (lite/full/ultra/off)"
prompt = "Switch to ponytail {{args}} mode. If no level specified, use full. ..."

```

Omitting the argument reports the current level. Runtime switches do not persist to the config file unless you explicitly call the `writeDefaultMode` API exposed in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).

## Customizing UI Behavior

Two boolean flags control startup and status visibility, each checked via environment variable first, then config file:

- **`PONYTAIL_QUIET_STARTUP`** or `"quietStartup": true` – Suppresses the "Ponytail loaded" toast (implemented in `getQuietStartup()`, lines 102-111)
- **`PONYTAIL_HIDE_STATUS`** or `"hideStatus": true` – Hides the status-line indicator (implemented in `getHideStatus()`, lines 119-128)

Both functions mirror the mode resolution logic, checking `process.env` before falling back to the JSON config.

## Extending and Customizing Skills

Ponytail ships with six core skills declared in [[`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml)](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml): `ponytail`, `ponytail-review`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, and `ponytail-help`.

To customize behavior:

1. **Copy a skill** to your project's `skills/` directory or host-specific location (e.g., `.qoder/plugins/`)
2. **Modify the implementation** in the `.md` or `.js` files—the skill loader auto-detects changes
3. **Refresh the host** (restart Copilot, reload Gemini extension) to re-read the files

The build script [[`scripts/build-openclaw-skills.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/build-openclaw-skills.js)](https://github.com/DietrichGebert/ponytail/blob/main/scripts/build-openclaw-skills.js) packages these into OpenClaw-compatible formats.

Example custom skill structure:

```markdown
<!-- skills/ponytail-echo/SKILL.md -->

# ponytail‑echo

Echo the current Ponytail mode for debugging.

```js
module.exports = async function (context) {
  const { getDefaultMode } = require('../hooks/ponytail-config');
  return `Current mode: ${await getDefaultMode()}`;
}

```

```

Then reference it in [`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml):

```yaml
skills:
  - path: skills/ponytail-echo
    name: ponytail-echo

```

## Summary

- **Environment variables** (`PONYTAIL_DEFAULT_MODE`, `PONYTAIL_QUIET_STARTUP`, `PONYTAIL_HIDE_STATUS`) take precedence over all other settings
- **Config file** at `~/.config/ponytail/config.json` (respecting `XDG_CONFIG_HOME` or `%APPDATA%`) stores persistent defaults for mode and UI flags
- **Runtime commands** (`/ponytail [mode]`) provide temporary session overrides without writing to disk
- **Skill customization** involves editing files in `skills/` and updating [`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml) to register new capabilities
- **File paths** resolve via `getConfigPath()` (lines 54-69) and `getConfigDir()` (lines 54-61), ensuring cross-platform compatibility

## Frequently Asked Questions

### How do I temporarily disable Ponytail for a single request without changing the default?

Send the command `/ponytail off` before your request. This switches the session to `off` mode immediately. To restore the previous level, send `/ponytail` without arguments or specify your preferred mode explicitly. The change affects only the current session and does not modify `~/.config/ponytail/config.json`.

### Can I use a custom configuration directory instead of `~/.config/ponytail`?

Yes. Set the `XDG_CONFIG_HOME` environment variable to your preferred path before launching the host. The resolver function `getConfigDir()` (lines 54-61) constructs the config path using `$XDG_CONFIG_HOME/ponytail/config.json` on Linux/macOS, or falls back to `%APPDATA%/ponytail/config.json` on Windows.

### Why can't I set `review` as the default mode in the config file?

The `review` mode is intentionally restricted to session-only usage. The configuration resolver in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) (lines 78-84) explicitly guards against persisting `review` as a default, ensuring it can only be invoked manually per conversation for targeted code audits.

### How do I add a new skill that logs every mode change?

Create a new directory under `skills/` (e.g., `skills/ponytail-logger/`) containing a [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) file with your handler logic. Import `getDefaultMode()` from [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) to access the current state. Add the skill path to [`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml) under the `skills:` key, then restart your AI host to load the extension.