How Ponytail Integrates with Claude Code: Plugin Architecture Deep Dive

Ponytail integrates with Claude Code as a native plugin using a declarative plugin.json manifest, TOML command definitions, and lifecycle hooks that activate the agent, track its mode, and update the UI status line.

Ponytail is an agent framework that extends Claude Code's capabilities through a plugin-based architecture. According to the DietrichGebert/ponytail source code, the integration relies on a specific directory structure and manifest files that Claude Code discovers at startup. This design enables zero-configuration installation and deep integration with the Claude development environment.

Plugin Manifest Declaration in /.claude-plugin/plugin.json

The integration begins with the plugin.json file located in the /.claude-plugin/ directory. This manifest declares Ponytail as a Claude Code plugin and enumerates resources the host should load, including commands, hooks, and skills. When Claude Code starts, it scans ~/.claude/plugins and reads this manifest to discover available functionality.

The manifest points to three critical components:

• Command definitions in commands/*.toml
• Lifecycle hooks in hooks/claude-codex-hooks.json
• Optional skill files for specialized sub-agents

Command Registration via TOML Configuration

Ponytail exposes functionality to Claude Code through TOML command files stored in the commands/ directory. Each file defines a CLI command that appears in both the Claude terminal and UI.

For example, commands/ponytail.toml implements the core agent launcher, while commands/ponytail-review.toml provides code review capabilities. Claude Code reads these definitions at startup and registers them as native commands available to the user.

Lifecycle Hooks and Session State Management

The hooks/claude-codex-hooks.json file registers scripts that execute at specific moments in the Claude Code lifecycle. This mechanism enables Ponytail to maintain state and provide real-time UI feedback.

Activation Hook (hooks/ponytail-activate.js)

When triggered, this script writes a flag file to ~/.claude/.ponytail-active, signaling that the Ponytail agent is enabled for the current session.

Mode Tracking (hooks/ponytail-mode-tracker.js)

This hook monitors whether the agent is in "run" or "idle" mode, keeping Claude Code synchronized with the agent's current state across sessions.

Status Line Integration (hooks/ponytail-statusline.sh and ponytail-statusline.ps1)

These shell scripts read the .ponytail-active flag file and output status text that Claude Code displays in its UI, providing visual confirmation when "Ponytail active".

Configuration Directory Resolution

The hooks/ponytail-config.js utility resolves the Claude Code configuration directory, respecting the CLAUDE_CONFIG_DIR environment variable. This allows Ponytail to locate the user's Claude home (defaulting to ~/.claude) and persist its own configuration to ~/.config/ponytail/config.json without hardcoded paths.

Skill-Based Sub-Agents

Beyond core commands, Ponytail ships with Markdown-based skills in the skills/ directory (e.g., skills/ponytail-help/SKILL.md and skills/ponytail-review/SKILL.md). Claude Code loads these as sub-agents that can be invoked conversationally, providing higher-level functionality like help prompts and guided reviews.

Installation and Activation Workflow

Installing Ponytail requires placing the plugin directory under ~/.claude/plugins. Once installed, Claude Code automatically loads the plugin on startup.

# Install Ponytail to the Claude plugins directory

# (Assumes repo cloned to ~/ponytail)

cp -r ~/ponytail ~/.claude/plugins/ponytail

# Activate Ponytail for the current session

node ~/.claude/plugins/ponytail/hooks/ponytail-activate.js

# Verify activation - check for the flag file

ls ~/.claude/.ponytail-active

# Run a Ponytail command from within Claude Code

ponytail review --input "./src/**/*.js"

# Check status line shows "Ponytail active"

The activation hook writes the .ponytail-active flag file that both the mode tracker and status line scripts monitor, enabling real-time state synchronization without manual intervention.

Summary

• Ponytail integrates with Claude Code through a declarative plugin manifest (/.claude-plugin/plugin.json) that Claude discovers at startup
• TOML command files (commands/*.toml) register CLI tools like ponytail and ponytail-review directly in the Claude interface
• Lifecycle hooks (hooks/claude-codex-hooks.json) handle activation, mode tracking, and UI status updates via flag files in ~/.claude/
• The configuration resolver (hooks/ponytail-config.js) supports custom Claude installation paths via CLAUDE_CONFIG_DIR
• Markdown skills (skills/.../SKILL.md) provide conversational sub-agents for specialized tasks

Frequently Asked Questions

Where does Claude Code look for the Ponytail plugin?

Claude Code scans the ~/.claude/plugins directory at startup. When Ponytail is placed there, Claude reads /.claude-plugin/plugin.json to load commands and hooks automatically.

How does Ponytail maintain state between Claude Code sessions?

Ponytail writes a flag file to ~/.claude/.ponytail-active via the hooks/ponytail-activate.js script. The hooks/ponytail-mode-tracker.js hook monitors this file to track whether the agent is active or idle.

Can I customize where Ponytail stores its configuration?

Yes. The hooks/ponytail-config.js helper respects the CLAUDE_CONFIG_DIR environment variable, allowing you to relocate the entire Claude configuration tree including Ponytail's state files.

What commands does Ponytail add to Claude Code?

Ponytail registers commands defined in commands/ponytail.toml (core agent) and commands/ponytail-review.toml (code review), making them available in both the Claude terminal and UI.

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