# How to Install Ponytail for Plugin-Based AI Hosts: Complete Setup Guide

> Install Ponytail for plugin-based AI hosts easily. This guide provides a complete setup, leveraging JSON hooks and portable skill scripts for seamless integration without extra dependencies.

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

---

**Ponytail installs as JSON hooks and portable skill scripts that plugin-compatible AI hosts load automatically, requiring no additional runtime dependencies beyond the host's standard marketplace or extension system.**

Ponytail is a token-minimization ruleset for AI-assisted coding distributed through the `DietrichGebert/ponytail` repository. When you install Ponytail for plugin-based AI hosts, you inject lifecycle-managed rules and slash commands that enforce aggressive context window management across every LLM turn. The architecture consists solely of JSON configuration files and small skill scripts, allowing any host supporting standard plugin packages to load Ponytail without external dependencies.

## Understanding the Plugin Architecture

Ponytail's distribution model relies on two core components that reside in the repository's `hooks/` and `skills/` directories.

### Hooks: Lifecycle Event Injection

Hooks are JSON files that define lifecycle events such as `UserPromptSubmit` and `PreToolUse` for each supported host. Located in [`hooks/claude-codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/claude-codex-hooks.json), [`hooks/qoder-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/qoder-hooks.json), and [`hooks/copilot-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/copilot-hooks.json), these files inject Ponytail's "always-on" ruleset during session initialization and register the `/ponytail` slash commands automatically.

### Skills: Command Implementation

The `skills/` directory contains six lightweight scripts that implement Ponytail's command set: `ponytail`, `ponytail-review`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, and `ponytail-help`. According to [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md), these scripts bundle the logic for each slash command and execute when invoked through the host's interface.

### Mode Switching State Machine

Ponytail implements a lightweight state machine supporting four modes: `lite`, `full`, `ultra`, and `off`. The current mode persists in a JSON file within the user's config directory or defaults to the value specified by the `PONYTAIL_DEFAULT_MODE` environment variable. This configuration determines how aggressively Ponytail's minimization rules apply to code generation.

## Host-Specific Installation Methods

Because Ponytail requires only JSON and script files, installation varies by host marketplace mechanism. The [`README.md`](https://github.com/DietrichGebert/ponytail/blob/main/README.md) in the repository root provides host-specific commands for each platform.

### Claude Code

For Claude Code, add the plugin from the marketplace:

```text
/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

```

### Codex CLI

Install via the Codex CLI plugin manager:

```bash
codex plugin marketplace add DietrichGebert/ponytail
codex plugin add ponytail@ponytail

```

### GitHub Copilot CLI

Use the Copilot CLI plugin commands:

```bash
copilot plugin marketplace add DietrichGebert/ponytail
copilot plugin install ponytail@ponytail

```

### Pi Agent Harness

Install directly from the Git repository:

```bash
pi install git:github.com/DietrichGebert/ponytail

```

### OpenCode

Add the plugin reference to your OpenCode configuration:

```json
{ "plugin": ["@dietrichgebert/ponytail"] }

```

### Gemini CLI and Antigravity CLI

For Gemini CLI:

```bash
gemini extensions install https://github.com/DietrichGebert/ponytail

```

For Antigravity CLI (formerly Gemini CLI):

```bash
agy plugin install https://github.com/DietrichGebert/ponytail

```

### Qoder

Copy the bundled rule file into your project directory:

```bash
cp .qoder/rules/ponytail.md .qoder/rules/

```

This references the hooks defined in [`hooks/qoder-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/qoder-hooks.json).

### Hermes Agent

Enable the plugin through the Hermes CLI:

```text
hermes plugins install DietrichGebert/ponytail --enable

```

### Devin CLI

Install via the Devin plugin manager:

```bash
devin plugins install DietrichGebert/ponytail

```

### Grok Build

Add to your Grok Build configuration file:

```toml
[plugins]
enabled = ["ponytail"]

```

## Configuration Files and State Management

After installation, Ponytail stores its state in the user's config directory as a JSON file tracking the current mode. You can override the default mode at the system level by setting the `PONYTAIL_DEFAULT_MODE` environment variable before launching the host.

The repository includes [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) as a plain-text alternative to the JSON hooks for hosts that support only instruction-only mode without full plugin capabilities.

## Key Source Files Reference

Understanding the repository structure helps troubleshoot installation issues:

- **[`hooks/claude-codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/claude-codex-hooks.json)**: Defines lifecycle hooks for Claude Code and Codex hosts, specifying event triggers like `UserPromptSubmit`.
- **[`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md)**: Documents the implementation details for the main `ponytail` skill and references the sibling directories containing the five other command scripts.
- **[`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)**: Provides the complete ruleset in plain text for hosts lacking JSON hook support.
- **[`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js)**: Removes lingering state files and configuration after removing the plugin from the host.

Once loaded, these files enable commands such as `/ponytail ultra` to immediately switch modes, or `/ponytail-review` to analyze existing code for token efficiency.

## Summary

- **Install Ponytail for plugin-based AI hosts** by loading JSON hooks and skill scripts through your host's standard marketplace or extension system.
- **Hooks** in [`hooks/claude-codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/claude-codex-hooks.json) and similar files automatically inject rules during `UserPromptSubmit` and other lifecycle events.
- **Skills** in the `skills/` directory implement six commands: `ponytail`, `ponytail-review`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, and `ponytail-help`.
- **Configuration** persists via JSON state files or the `PONYTAIL_DEFAULT_MODE` environment variable, supporting `lite`, `full`, `ultra`, and `off` modes.
- **Zero dependencies** are required beyond the host's native plugin loader, as Ponytail consists only of configuration and script files.

## Frequently Asked Questions

### What file formats does Ponytail use for installation?

Ponytail distributes as JSON hook files defining lifecycle events and plain-text skill scripts. The `hooks/` directory contains host-specific JSON configurations like [`hooks/copilot-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/copilot-hooks.json), while the `skills/` directory contains implementation scripts. For hosts without plugin support, the plain-text [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) file provides the complete instruction set.

### How do I switch between Ponytail's operating modes?

Use the `/ponytail` slash command followed by the mode name: `/ponytail lite`, `/ponytail full`, `/ponytail ultra`, or `/ponytail off`. The host stores this preference in a JSON file within your config directory. Alternatively, set the `PONYTAIL_DEFAULT_MODE` environment variable to enforce a specific mode at startup.

### Can I use Ponytail with hosts that don't support plugins?

Yes. Hosts that support instruction-only mode can load Ponytail through the [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) file instead of the JSON hooks. Copy the contents of [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) into your host's system prompt or rules section to achieve the same minimization behavior without formal plugin installation.

### How do I completely uninstall Ponytail?

First, remove the plugin using your host's uninstall command, then run the [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) cleanup script to delete residual state files and configuration data. This ensures the mode settings and cached hooks are fully purged from your system.