# What Is the `hooks/` Directory in Ponytail? Understanding the Core Architecture

> Explore the `hooks/` directory in Ponytail and understand its vital role in integrating with AI assistant platforms like Claude, Codex, Gemini, and Pi by reacting to platform specific events.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: architecture
- Published: 2026-09-07

---

**The `hooks/` directory is the central lifecycle-hook integration layer that enables Ponytail to embed into multiple AI assistant platforms (Claude, Codex, Gemini, Pi) and react to platform-specific events.**

If you're building or extending Ponytail, the `hooks/` directory is where the magic happens. Located at the root of the [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) repository, this directory contains everything needed to transform Ponytail from a simple library into a fully-featured plugin. The architecture centralizes hook definitions, runtime utilities, and configuration handling so that the same core logic works across every supported host environment.

## Key Responsibilities of the `hooks/` Directory

The `hooks/` directory serves eight critical functions in Ponytail's architecture. Each responsibility is implemented through specific source files that work together as a cohesive system.

### Expose Platform-Specific Hook Manifests

JSON manifest files map host-specific hook names to the commands Ponytail executes. These manifests live directly in `hooks/`:

- [`qoder-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/qoder-hooks.json) — maps Qoder events like `UserPromptSubmit` to handler scripts
- [`claude-codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/claude-codex-hooks.json) — defines hooks for Claude and Codex environments
- [`hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks.json) — generic manifest for other compatible hosts

Here's how a hook binding looks in practice:

```json
// hooks/qoder-hooks.json
{
  "hooks": {
    "command.execute.before": [
      {
        "hooks": [
          { "command": "node", "args": ["hooks/ponytail-mode-tracker.js"] }
        ]
      }
    ]
  }
}

```

### Provide Runtime Utilities

[`ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-runtime.js) is the core loader that detects the host environment, loads the appropriate manifest, and forwards events to the shared implementation. This utility ensures that platform-specific differences are abstracted away from the business logic.

```javascript
// Example pattern from ponytail-runtime.js
const { loadPlugin } = require('./ponytail-runtime');

async function onCommandExecute(event) {
  const plugin = await loadPlugin({});
  await plugin['command.execute.before'](event);
}

```

### Centralize Configuration and Mode Handling

[`ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-config.js) acts as the single source of truth for Ponytail's behavior. It resolves the default mode, reads and writes user configuration, and provides helper predicates like `isShellSafe()` and `isDeactivationCommand()`. Every hook implementation imports this module, ensuring consistent configuration access across the entire system.

### Track and Persist Mode State

[`ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mode-tracker.js) monitors activation and deactivation commands, then persists the chosen mode so that every host sees consistent state. When a user switches Ponytail modes, this script writes the update and ensures all connected environments reflect the change.

### Enable Activation Helpers

[`ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-activate.js) provides a convenience script that copies the `hooks/` directory into a host's plugin folder. This simplifies installation across different AI assistant marketplaces.

```bash

# On Unix-like shells

node hooks/ponytail-activate.js

```

### Build Instruction Sets for Extensions

[`ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-instructions.js) generates a unified instruction set consumed by the Pi extension and other adapters. This ensures that extension-specific formatting and behavior remain consistent with the core Ponytail logic.

### Support Status-Line Integration

Platform-native shell scripts provide visual indicators of Ponytail's current state:

- [`ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-statusline.sh) — POSIX shell implementation
- `ponytail-statusline.ps1` — PowerShell implementation

These scripts integrate with the host's command prompt to display the active Ponytail mode.

### Enable Sub-Agent Entry Points

[`ponytail-subagent.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-subagent.js) launches a separate Node process that maintains Ponytail state when the host spawns a sub-agent. This is critical for complex workflows where the primary assistant delegates tasks to specialized sub-agents that still need access to Ponytail functionality.

## Architectural Benefits of the `hooks/` Directory

By centralizing all hook-related code in one location, Ponytail achieves three major design goals:

- **Code reuse** — The same JavaScript handlers work across different host-specific manifests. No logic duplication between Claude and Codex adapters.
- **Behavioral consistency** — Mode resolution, configuration handling, and status-line updates work identically regardless of which plugin marketplace a user installs from.
- **Clear extension points** — New hosts only need to create a manifest file pointing to `hooks/<manifest>.json`. The runtime automatically loads appropriate handlers.

## Summary

- The `hooks/` directory is Ponytail's **lifecycle-hook integration layer**, enabling multi-platform AI assistant support.
- **Hook manifests** ([`qoder-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/qoder-hooks.json), [`claude-codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/claude-codex-hooks.json)) map platform events to handler scripts.
- **Runtime utilities** ([`ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-runtime.js)) abstract host detection and event dispatch.
- **Configuration centralization** ([`ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-config.js)) ensures consistent behavior across all environments.
- **Mode tracking** ([`ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mode-tracker.js)) persists state across sessions and hosts.
- **Activation scripts** ([`ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-activate.js)) simplify cross-platform installation.
- **Status-line integration** (shell and PowerShell scripts) provides visual state indicators.
- **Sub-agent support** ([`ponytail-subagent.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-subagent.js)) extends functionality to delegated tasks.

## Frequently Asked Questions

### What file should I modify to add support for a new AI assistant platform?

Create a new JSON manifest file in `hooks/` following the pattern of [`qoder-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/qoder-hooks.json) or [`claude-codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/claude-codex-hooks.json). Map the platform's native hook names to the appropriate handler scripts in `hooks/`. You typically won't need to modify the JavaScript utilities—just reference them from your new manifest.

### How does Ponytail maintain consistent state when I switch between Claude and Codex?

[`ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mode-tracker.js) writes mode changes to persistent storage, and [`ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-config.js) provides the single source of truth that all hosts read from. When you activate Ponytail in one environment, the mode tracker updates the shared configuration, and the next environment you open will read that same state through [`ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-config.js).

### Can I customize which hooks fire for a specific host?

Yes. Each manifest file in `hooks/` independently defines which events trigger Ponytail actions. You can include or exclude specific hook entries in your custom manifest, or point events to different handler scripts while still using the shared runtime utilities for consistency.