# Core Ponytail Commands and Their Functions: The Complete CLI Reference

> Discover core Ponytail commands like /ponytail-review and /ponytail-audit. Learn how to manage AI intensity and technical debt with this comprehensive CLI reference. Boost your development workflow.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: api-reference
- Published: 2026-09-04

---

**The six core Ponytail commands—`/ponytail`, `/ponytail-review`, `/ponytail-audit`, `/ponytail-debt`, `/ponytail-gain`, and `/ponytail-help`—enable developers to toggle AI intensity levels, audit over-engineered code, and track technical debt through declarative TOML definitions processed by the [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) engine.**

Ponytail is an open-source AI assistant developed in the `DietrichGebert/ponytail` repository that simulates a "lazy senior developer" to reduce code bloat. Instead of hard-coding logic for every operation, **core Ponytail commands and their functions** are defined as separate `.toml` configuration files, allowing the runtime to dynamically translate user intent into LLM prompts. This architectural choice keeps the command layer thin while delegating complex analysis to the underlying language model.

## Architectural Overview: Declarative Commands and Runtime Execution

### TOML-Based Command Definitions

Each command resides as a standalone configuration file under the `commands/` directory. These files contain human-readable metadata (`description`) and the actual instructions (`prompt`) sent to the AI. For example, when you invoke `/ponytail-review`, the runtime loads [[`commands/ponytail-review.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml), extracts its prompt template, and forwards it to the LLM along with contextual data such as the current git diff.

### The Runtime Engine ([`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js))

The [[`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) file serves as the orchestration bridge. It handles TOML parsing, environment variable injection, and LLM API communication. By separating command semantics (the "what") from execution logic (the "how"), Ponytail allows new commands to be added simply by dropping new `.toml` files into the `commands/` folder without modifying JavaScript code.

### Configuration Management ([`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js))

Default behavior is governed by [[`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), which reads the `PONYTAIL_DEFAULT_MODE` environment variable (accepting `lite`, `full`, `ultra`, or `off`) and locates user-specific override files. This ensures that intensity levels persist across sessions while remaining configurable per repository.

## The Six Core Ponytail Commands Explained

### /ponytail – Switching Intensity Modes

**Source:** [[`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml)

This is the primary mode-switching command. It accepts one argument that determines how aggressively the AI applies the "lazy ladder" heuristic (YAGNI → stdlib → native → one-liner → minimum):

- **`lite`** – Conservative suggestions, minimal changes.
- **`full`** – Standard over-engineering detection (default if no argument provided).
- **`ultra`** – Aggressive deletion-first policy; prefers removing code over adding abstraction.
- **`off`** – Deactivates Ponytail, returning to normal development mode.

### /ponytail-review – Over-Engineering Code Review

**Source:** [[`commands/ponytail-review.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml)

Use this command to analyze uncommitted changes or staged files. The LLM returns a list of one-line suggestions tagged according to the type of simplification required:

- **`delete`** – Remove unnecessary code entirely.
- **`stdlib`** – Replace custom logic with standard library equivalents.
- **`native`** – Use language-native features instead of polyfills or wrappers.
- **`yagni`** – Remove speculative functionality (You Aren't Gonna Need It).
- **`shrink`** – Compress verbose implementations.

Each suggestion may include a replacement code block that can be applied directly.

### /ponytail-audit – Repository-Wide Over-Engineering Audit

**Source:** [[`commands/ponytail-audit.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-audit.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-audit.toml)

While `/ponytail-review` focuses on active changes, the audit command scans the entire repository for systemic over-engineering patterns. It surfaces architectural debt such as excessive abstraction layers, redundant utility classes, and microservice granularity issues that violate the "lazy senior dev" philosophy.

### /ponytail-debt – Harvesting Technical Debt

**Source:** [[`commands/ponytail-debt.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml)

This command aggregates AI-generated comments (marked with `delete`, `yagni`, or other tags from previous reviews) into a structured **debt ledger**. This persistent record allows teams to schedule dedicated refactoring sprints to address earmarked removals without losing track of simplification opportunities discovered during daily development.

### /ponytail-gain – Impact Scoreboard and Benchmarks

**Source:** [[`commands/ponytail-gain.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-gain.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-gain.toml)

After applying Ponytail suggestions, use this command to visualize measurable improvements. The runtime queries benchmark medians to display:

- **Lines of Code (LOC)** reduction percentage.
- **Execution speed** improvements.
- **Infrastructure cost** savings (where applicable).

This read-only command provides the business justification for aggressive simplification by quantifying technical debt removal.

### /ponytail-help – Quick Reference Card

**Source:** [[`commands/ponytail-help.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-help.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-help.toml)

The help command prints an inline cheat sheet listing all available intensity levels, recognized skill tags, and deactivation syntax (`/ponytail off`, `stop ponytail`, or `normal mode`). It is particularly useful for onboarding new team members or verifying the current mode setting without reading source documentation.

## Practical Usage Examples

```bash

# Activate ultra-aggressive deletion mode

/ponytail ultra

# Review current branch changes for over-engineering

/ponytail-review

# Scan the entire repo for systemic complexity

/ponytail-audit

# Persist today's "delete" suggestions to the debt ledger

/ponytail-debt

# Show measurable impact from previous optimizations

/ponytail-gain

# Print quick-reference and current configuration

/ponytail-help

# Deactivate Ponytail for normal coding sessions

/ponytail off

```

## Key Source Files and Implementation Details

| File | Role |
|------|------|
| [[`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml) | Intensity mode switching (`lite`, `full`, `ultra`, `off`). |
| [[`commands/ponytail-review.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml) | Prompt template for change-set over-engineering review. |
| [[`commands/ponytail-audit.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-audit.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-audit.toml) | Prompt template for repository-wide architectural audits. |
| [[`commands/ponytail-debt.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml) | Logic for harvesting tagged comments into the debt ledger. |
| [[`commands/ponytail-gain.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-gain.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-gain.toml) | Prompt for generating benchmark-derived impact reports. |
| [[`commands/ponytail-help.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-help.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-help.toml) | Quick-reference documentation prompt. |
| [[`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) | Core engine that loads TOML definitions and manages LLM communication. |
| [[`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) | Environment variable handling and default mode resolution. |

## Summary

- **Six declarative commands** control AI intensity and code analysis workflows in Ponytail.
- **Command definitions** reside in `commands/*.toml` files, making the system extensible without JavaScript changes.
- **`/ponytail`** switches between `lite`, `full`, and `ultra` modes; **`/ponytail-review`** and **`/ponytail-audit`** detect over-engineering at different scopes.
- **`/ponytail-debt`** tracks removal candidates in a persistent ledger, while **`/ponytail-gain`** quantifies optimization impact.
- **Execution flow** is handled by [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) with configuration managed via [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) and environment variables.

## Frequently Asked Questions

### What is the difference between `/ponytail-review` and `/ponytail-audit`?

**`/ponytail-review`** analyzes currently staged or unstaged code changes (the active diff), providing immediate feedback on over-engineering introduced in the current work session. **`/ponytail-audit`** performs a holistic scan of the entire repository, identifying systemic architectural issues and legacy complexity that exists outside of recent commits.

### How does the runtime engine process TOML command definitions?

When a user invokes a command, [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) reads the corresponding file from the `commands/` directory, extracts the `prompt` field, and injects contextual data such as git state or file trees. The runtime then sends this composite prompt to the configured LLM API and parses the response to present tagged suggestions or execute state changes like mode switching.

### Can I extend Ponytail with custom commands?

Yes. Because the command layer is declarative, you can create new functionality by adding a `.toml` file to the `commands/` directory with `description` and `prompt` keys. The runtime automatically discovers and loads these files at startup, allowing you to define custom AI workflows (e.g., security reviews, documentation generation) without modifying the core JavaScript runtime.

### Where is the technical debt ledger stored?

The debt ledger is generated and managed by the **`/ponytail-debt`** command as defined in [`commands/ponytail-debt.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml). While the exact persistence mechanism depends on the runtime implementation, the ledger typically writes to a project-local JSON or Markdown file (often [`.ponytail/debt.md`](https://github.com/DietrichGebert/ponytail/blob/main/.ponytail/debt.md) or similar) that can be committed to version control or processed by CI pipelines to track refactoring progress.