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

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, 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.

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 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 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, 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 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 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:

/ponytail ultra

The ponytail-runtime.js module processes this through the mode tracker and returns:

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:

codex plugin use @ponytail-review

This command directs the host to load 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:

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

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, 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 – Core runtime that parses modes, dispatches commands, and exports the public API functions (review(), audit(), etc.)
• hooks/ponytail-mode-tracker.js – Intercepts user prompts to detect /ponytail commands and manages the .ponytail-active flag file
• hooks/ponytail-config.js – Resolves configuration from environment variables and ~/.config/ponytail/config.json
• hooks/ponytail-subagent.js – Ensures ruleset injection into every spawned sub-agent
• hooks/ponytail-activate.js – Handles SessionStart lifecycle events to initialize the API state
• skills/ponytail/SKILL.md – Formal definition of the primary skill for hosts using the skill protocol
• 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.
• Configuration persists via PONYTAIL_DEFAULT_MODE environment variable or ~/.config/ponytail/config.json, resolved by hooks/ponytail-config.js.
• The runtime in 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 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 file updates this flag when users issue /ponytail commands, and 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 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 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.

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