# How to Use the `/ponytail` Command to Switch Intensity Modes

> Master the /ponytail command to switch intensity modes lite, full, ultra, or off. Learn to set default modes for persistent code-generation settings in Ponytail.

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

---

**Use `/ponytail <mode>` to change Ponytail's code‑generation intensity, where `<mode>` is `lite`, `full`, `ultra`, `off`, or `default <mode>` to persist your choice for future sessions.**

The `/ponytail` command is the primary interface for controlling how aggressively Ponytail guides your LLM-assisted coding. Whether you want minimal hints or exhaustive step‑by‑step instructions, this command lets you dial in the right level of assistance. This guide walks through the exact syntax, available intensity levels, and how the [`ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mode-tracker.js) hook processes your commands.

## Understanding Intensity Modes

Ponytail defines three active intensity levels plus an off state:

- **`lite`** — Lightweight guidance with high‑level suggestions
- **`full`** — Standard, detailed code‑generation instructions
- **`ultra`** — Maximum verbosity with exhaustive explanations
- **`off`** — Disables Ponytail for the current session only

Intensity modes control the depth of instructions injected into your LLM prompts. According to the DietrichGebert/ponytail source, the mode tracker in [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) validates these options at lines 31‑55 before activating any changes.

## Basic Syntax for Switching Modes

### Session-Only Mode Changes

To change intensity for the current conversation without affecting future sessions:

```javascript
// Switch to lite intensity
{ "prompt": "/ponytail lite" }

// Switch to full intensity
{ "prompt": "/ponytail full" }

// Switch to ultra intensity
{ "prompt": "/ponytail ultra" }

```

The `finish()` function in `hooks/ponytail-mode-tracker.js:18‑23` parses your prompt, normalizes it to lowercase, and extracts the command at lines 23‑27. If a valid runtime mode is detected, `setMode(mode)` (lines 64‑80) stores the flag file and emits confirmation.

### Persisting a Default Mode

To save your preferred intensity for all future sessions:

```javascript
// Persist ultra as the default
{ "prompt": "/ponytail default ultra" }

```

The `writeDefaultMode(dmode)` function at lines 38‑44 persists your choice to `~/.config/ponytail/config.json` (respecting XDG directories). On the next session, `getDefaultMode()` in `hooks/ponytail-config.js:76‑85` reads this value automatically.

## Checking and Disabling Intensity

### Query Current Mode

Running `/ponytail` without arguments reports the active intensity without making changes:

```javascript
{ "prompt": "/ponytail" }

```

The hook responds with the current mode status, useful for verifying your configuration.

### Disable Ponytemporarily

To turn off Ponytail guidance for the remainder of the session:

```javascript
{ "prompt": "/ponytail off" }

```

Unlike mode changes, `off` clears the flag file rather than writing a new one (lines 64‑80). This state does **not** persist—your saved default will reactivate on the next session.

## How the Mode Tracker Processes Commands

The [`ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mode-tracker.js) hook operates in six distinct stages when handling `/ponytail` commands:

1. **Parse input** — `finish()` reads `data.prompt` and normalizes case (lines 18‑23)
2. **Detect command** — Identifies `/ponytail` or `@/ponytail` prefix (lines 23‑27)
3. **Route arguments** — Dispatches to `default`, mode setter, or report handler (lines 31‑55)
4. **Activate mode** — `setMode()` writes flag file or clears for `off` (lines 64‑80)
5. **Persist if requested** — `writeDefaultMode()` updates config.json (lines 38‑44)
6. **Emit feedback** — `writeHookOutput()` returns JSON with confirmation (lines 58‑63)

The response format follows this structure:

```json
{
  "type": "UserPromptSubmit",
  "data": "lite",
  "message": "PONYTAIL MODE CHANGED — level: lite"
}

```

## Command Reference

| Command | Effect | Persistence |
|---------|--------|-------------|
| `/ponytail lite` | Lite intensity guidance | Session only |
| `/ponytail full` | Full intensity guidance | Session only |
| `/ponytail ultra` | Ultra intensity guidance | Session only |
| `/ponytail off` | Disable Ponytail | Session only |
| `/ponytail default <mode>` | Set `<mode>` as new default | Permanent |
| `/ponytail` | Report current mode | None |

## Related Files in the Repository

| File | Purpose |
|------|---------|
| [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) | Core command parser and mode state manager |
| [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) | Config file I/O and environment resolution |
| [`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js) | Generates human‑readable instruction text post‑switch |
| [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) | Registers `/ponytail` for Pi extension hosts |

## Summary

- `/ponytail` accepts `lite`, `full`, `ultra`, `off`, or `default <mode>` as arguments
- Runtime modes apply immediately but expire with the session
- `default <mode>` writes to `~/.config/ponytail/config.json` via `writeDefaultMode()`
- Blank `/ponytail` queries without changing state
- The mode tracker in [`ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mode-tracker.js) handles all parsing, validation, and state management

## Frequently Asked Questions

### What happens if I type an invalid mode?

The hook validates arguments at lines 31‑55 in [`ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mode-tracker.js). Unrecognized modes trigger an error response without changing your current configuration. Only `lite`, `full`, `ultra`, and `off` are accepted as runtime values.

### Can I use `/ponytail` in any LLM host?

Yes. The command is registered globally via [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js), and the mode tracker hook processes prompts regardless of whether you use Claude, Gemini, or another supported host. The hook runs on every `UserPromptSubmit` event.

### Where is my default mode actually stored?

`writeDefaultMode()` writes to the XDG-compliant configuration path, typically `~/.config/ponytail/config.json`. The exact location respects your `XDG_CONFIG_HOME` environment variable as implemented in `ponytail-config.js:76‑85`.

### Does `/ponytail off` delete my saved default?

No. The `off` command only clears the session flag via `setMode()` at line 70. Your persisted default remains intact in the config file and will automatically restore on your next session initialization.