# How Ponytail Integrates with Claude Code: Plugin Architecture Deep Dive > Discover how Ponytail integrates with Claude Code via a native plugin architecture. Learn about its plugin.json manifest, TOML definitions, and lifecycle hooks for agent activation and UI status updates. - Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) - Tags: deep-dive - Published: 2026-08-28 --- **Ponytail integrates with Claude Code as a native plugin using a declarative [`plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main//.claude-plugin/plugin.json) The integration begins with the [`plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml) implements the core agent launcher, while [`commands/ponytail-review.toml`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-help/SKILL.md) and [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/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. ```bash # 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`](https://github.com/DietrichGebert/ponytail/blob/main//.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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)) supports custom Claude installation paths via `CLAUDE_CONFIG_DIR` - **Markdown skills** ([`skills/.../SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main//.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`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) script. The [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml) (core agent) and [`commands/ponytail-review.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml) (code review), making them available in both the Claude terminal and UI.