# Ponytail's API for Developers: Command-Line and Skill-Based Integration Guide

> Explore Ponytail's API for developers to integrate AI code pruning and audit capabilities. Leverage slash commands and portable skill files for Claude Code, Codex, Gemini, and more.

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

---

**Ponytail's API for developers exposes a "lazy-senior-dev" skill set through six slash commands and portable skill files that inject rulesets into every LLM turn, enabling code pruning and audit capabilities across Claude Code, Codex, Gemini, and other AI-agent hosts.**

Ponytail's API for developers provides a lightweight, stateless interface for AI-assisted code optimization within the DietrichGebert/ponytail repository. The system implements a command-line-style API alongside structured skill files, allowing developers to invoke code review, auditing, and technical debt tracking from any supported host environment. According to the source code analysis, the entire runtime is deliberately stateless per turn except for a mode flag, ensuring compatibility with any LLM that processes single prompt/response cycles.

## Core Concepts of the Ponytail API

### Modes and Intensity Levels

The API operates through four distinct **modes** that control how aggressively Ponytail strips over-engineered code: `lite`, `full` (default), `ultra`, and `off`. The current mode persists in a flag file (`.ponytail-active`) at the project root. In [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js), the runtime reads this flag to determine which ruleset to inject into the LLM context. Developers switch modes using the `/ponytail` command followed by the desired intensity level.

### Commands and Skills

Ponytail's API exposes six top-level **slash commands** that perform distinct actions across the codebase:

- `/ponytail` – Sets or queries the current intensity mode
- `/ponytail-review` – Prunes the current diff for over-engineering
- `/ponytail-audit` – Audits the entire repository for complexity
- `/ponytail-debt` – Lists deferred shortcuts and technical debt
- `/ponytail-gain` – Displays benchmark impact showing LOC, token, cost, and time reductions
- `/ponytail-help` – Displays quick reference documentation

Each command is also packaged as a **skill file** under the `skills/` directory. Hosts that understand the skill protocol (such as Codex, Gemini, or OpenCode) can invoke them using `@ponytail-review` or `$ponytail-gain` syntax, loading the markdown definitions directly from paths like [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md).

### Configuration System

The API supports persistent defaults through environment variables and JSON configuration. The `PONYTAIL_DEFAULT_MODE` environment variable sets the initial mode for new sessions. Alternatively, developers can create a config file at `~/.config/ponytail/config.json`. The [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) module resolves these settings, providing the default mode to the runtime before any user interaction occurs.

## How the Ponytail API Works

### Activation and Session Management

When a session begins, the [`ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-activate.js) hook triggers on the SessionStart event. This lifecycle hook writes the `.ponytail-active` flag file and emits the ruleset as hidden context to the LLM. Every subsequent user prompt is intercepted by [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js), which detects `/ponytail` commands, updates the flag file accordingly, and returns confirmation messages to the host.

### Command Dispatch and Runtime Functions

The [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) module exports the core API functions that handle command execution. When a user invokes `/ponytail-review`, the host calls the `review()` function exported from this module. Similarly, `audit()`, `debt()`, `gain()`, and `help()` functions handle their respective commands. These functions read the current mode from the flag file, load the appropriate skill markdown from the `skills/` directory, and return structured responses that the host renders to the user.

### Sub-Agent Rule Injection

To ensure consistency across complex operations, [`hooks/ponytail-subagent.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-subagent.js) intercepts every sub-agent spawned by the host (such as tool-use sub-agents in Claude Code or Codex). This hook injects the Ponytail ruleset into each sub-agent context, maintaining the "lazy-senior-dev" philosophy throughout the entire call chain regardless of how many AI processes are spawned.

## Implementing the Ponytail API: Code Examples

### Switching Modes via Slash Commands

To change the pruning intensity from any supported host, send the mode command directly:

```text
/ponytail ultra

```

The [`ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-runtime.js) module processes this through the mode tracker and returns:

```text
PONYTAIL MODE ACTIVE — level: ultra. Behavior defined by /ponytail-ultra skill.

```

### Invoking Skills in Compatible Hosts

For AI agents that support skill protocols, invoke Ponytail capabilities without slash commands:

```bash
codex plugin use @ponytail-review

```

This command directs the host to load [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) and execute the review logic against the current working directory.

### Querying Metrics and Technical Debt

To view optimization benchmarks or track deferred work:

```text
/ponytail-gain

```

This returns a markdown table showing lines of code, token usage, cost estimates, and time savings. Similarly, `/ponytail-debt` lists shortcuts marked for future refactoring.

### Programmatic Integration with the Runtime

Developers can import Ponytail's API directly into Node.js scripts using the internal runtime module:

```javascript
const { readMode, review, writeMode } = require('./hooks/ponytail-runtime');

async function optimizeCodebase() {
  // Set mode programmatically
  await writeMode('lite');
  
  // Run a review on the current diff
  const result = await review();
  console.log(result);
  
  // Check current mode
  const currentMode = await readMode();
  console.log(`Active mode: ${currentMode}`);
}

```

All helper functions are exported from [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js), making the API accessible for custom tooling and CI/CD pipelines.

## Key Source Files in the Ponytail API Architecture

Understanding the repository structure is essential for developers extending or debugging Ponytail's API:

- **[`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js)** – Core runtime that parses modes, dispatches commands, and exports the public API functions (`review()`, `audit()`, etc.)
- **[`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js)** – Intercepts user prompts to detect `/ponytail` commands and manages the `.ponytail-active` flag file
- **[`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)** – Resolves configuration from environment variables and `~/.config/ponytail/config.json`
- **[`hooks/ponytail-subagent.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-subagent.js)** – Ensures ruleset injection into every spawned sub-agent
- **[`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js)** – Handles SessionStart lifecycle events to initialize the API state
- **[`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md)** – Formal definition of the primary skill for hosts using the skill protocol
- **[`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md)** – Skill definition for code review operations

These files constitute the complete public API surface as implemented in DietrichGebert/ponytail, providing both declarative skill interfaces and imperative programmatic access.

## Summary

- Ponytail's API for developers provides six slash commands (`/ponytail`, `/ponytail-review`, `/ponytail-audit`, `/ponytail-debt`, `/ponytail-gain`, `/ponytail-help`) and corresponding skill files for AI-agent integration.
- The system uses four intensity modes (`lite`, `full`, `ultra`, `off`) stored in `.ponytail-active` and managed by [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js).
- Configuration persists via `PONYTAIL_DEFAULT_MODE` environment variable or `~/.config/ponytail/config.json`, resolved by [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).
- The runtime in [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) exports functions like `review()` and `audit()` for programmatic use in Node.js environments.
- Sub-agent injection via [`hooks/ponytail-subagent.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-subagent.js) ensures consistent ruleset application across complex multi-step AI operations.

## Frequently Asked Questions

### Which AI-agent hosts support Ponytail's API?

Ponytail's API for developers works with any host that processes text-based slash commands or implements a skill protocol. Supported platforms include Claude Code, Codex, Gemini, OpenCode, Hermes, and Qoder. Skill-aware hosts can load markdown definitions directly from the `skills/` directory using `@` or `$` prefixes, while standard hosts process the slash-command syntax natively.

### How does Ponytail maintain state across LLM turns?

The API is **stateless per turn** except for the mode flag stored in `.ponytail-active`. The [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) file updates this flag when users issue `/ponytail` commands, and [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) reads it at the start of each operation. This design ensures compatibility with single prompt/response cycles while maintaining persistent configuration across a session.

### Can I use Ponytail's API outside of AI-agent environments?

Yes. The [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) module exports JavaScript functions (`review()`, `audit()`, `readMode()`, `writeMode()`) that can be imported into Node.js applications. This allows developers to build custom CLI tools, pre-commit hooks, or CI/CD integrations that invoke Ponytail's pruning logic programmatically without requiring an AI host.

### Where are skill files located in the repository?

Skill files reside in subdirectories under `skills/` at the repository root. Each command has its own directory (e.g., `skills/ponytail-review/`, `skills/ponytail-audit/`) containing a [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) file that defines the command's behavior, parameters, and examples for skill-aware hosts. The primary `ponytail` skill is located at [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md).