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

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), while skill declarations live in [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 (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"

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

{
  "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#L1-L3):

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.

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): 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) packages these into OpenClaw-compatible formats.

Example custom skill structure:

<!-- 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 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 (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 file with your handler logic. Import getDefaultMode() from hooks/ponytail-config.js to access the current state. Add the skill path to plugin.yaml under the skills: key, then restart your AI host to load the extension.

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