> ## Documentation Index
> Fetch the complete documentation index at: https://ulpi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Zero merge conflicts. Perfect coordination. 8 lifecycle hooks for any AI coding assistant.

# 8 Lifecycle Hooks for Perfect AI Agent Coordination

**Your AI agents work in isolation. They overwrite each other's changes. Critical context disappears before compaction. Important messages get missed.**

**ULPI Hooks fixes all of this—automatically.**

<CardGroup cols={2}>
  <Card title="Zero Merge Conflicts" icon="shield-check" color="#10b981">
    Pre-edit hooks check file reservations and block conflicting changes before they happen
  </Card>

  <Card title="Context Preserved" icon="brain" color="#8b5cf6">
    Pre-compact hooks create memory snapshots before Claude compresses context
  </Card>

  <Card title="Never Miss Messages" icon="bell" color="#f59e0b">
    User-prompt hooks alert agents to urgent coordination messages
  </Card>

  <Card title="Clean Shutdowns" icon="power" color="#3b82f6">
    Session-end hooks release all file reservations and complete pending tasks
  </Card>
</CardGroup>

***

## The Problem: AI Assistants Work in Silos

You've experienced this frustration working with multiple AI coding assistants:

* **Constant merge conflicts** when two agents edit the same file
* **Lost context** when Claude compacts your conversation history
* **Missed urgent messages** from other agents on your team
* **Orphaned file locks** when sessions crash without cleanup
* **No coordination** between Claude Code, Cursor, and other tools

**Your AI team needs integration points. Hooks provides them.**

***

## The Solution: Deep Lifecycle Integration

ULPI Hooks intercepts 8 critical lifecycle events in your AI coding assistant and enables:

<Tabs>
  <Tab title="Without Hooks">
    ### The Chaos of Uncoordinated Agents

    **File Conflicts:**

    * Agent A edits `auth.ts`
    * Agent B edits `auth.ts` at the same time
    * Merge conflict requires manual resolution
    * **15 minutes lost**

    **Lost Context:**

    * Important architecture decision discussed
    * Context approaches token limit
    * Claude compacts conversation
    * Decision details lost forever
    * **Must re-explain from scratch**

    **Missed Messages:**

    * Security issue found by Agent A
    * Agent B doesn't see the urgent message
    * Deploys vulnerable code
    * **Critical bug reaches production**
  </Tab>

  <Tab title="With ULPI Hooks">
    ### Automatic Coordination

    **File Conflict Prevention:**

    * Agent A edits `auth.ts`
    * **Pre-edit hook** reserves the file automatically
    * Agent B attempts to edit `auth.ts`
    * **Blocked by hook** with clear message
    * Agent B coordinates via messaging instead
    * **Zero conflicts, zero time lost**

    **Context Preservation:**

    * Important architecture decision discussed
    * Context approaches token limit
    * **Pre-compact hook** fires automatically
    * Creates memory snapshot of decision
    * Claude compacts conversation safely
    * **Critical context preserved**

    **Urgent Message Alerts:**

    * Security issue found by Agent A
    * Urgent message sent to Agent B
    * **User-prompt hook** shows alert banner
    * Agent B sees issue before responding
    * Addresses security flaw immediately
    * **Zero bugs reach production**
  </Tab>
</Tabs>

***

## 8 Strategic Lifecycle Hooks

Each hook intercepts a critical moment in your AI assistant's lifecycle:

<AccordionGroup>
  <Accordion title="🚀 session-start: Register Agent & Load Context" icon="play">
    **Fires when:** Your AI coding assistant starts a new session

    **What it enables:**

    * Automatic agent registration with ULPI Coordination
    * Display coordination dashboard with active agents
    * Show file reservations from other agents
    * Initialize memory context from previous sessions
    * Present urgent messages waiting for acknowledgment

    **Exit Codes:**

    * `0` - Allow session to start normally
    * `2` - Block session (e.g., critical pending acknowledgments)

    **Performance:** \~150ms average latency
  </Accordion>

  <Accordion title="🔒 pre-tool-use:edit: Prevent File Conflicts" icon="lock">
    **Fires before:** Any file edit operation

    **What it enables:**

    * Check file reservations in Coordination system
    * Block edits if another agent has claimed the file
    * Auto-reserve files on first edit (shared or exclusive mode)
    * Show which agent has the file reserved
    * Suggest coordination via messaging

    **Exit Codes:**

    * `0` - Allow edit (file available or already reserved by this agent)
    * `2` - Block edit (file reserved by another agent)

    **Performance:** \~120ms average latency

    **Result:** Zero merge conflicts, guaranteed
  </Accordion>

  <Accordion title="📋 post-tool-use:edit: Track Obligations" icon="clipboard-check">
    **Fires after:** Any file edit operation completes

    **What it enables:**

    * Show pending tasks related to edited file
    * Display required acknowledgments
    * Track what needs review after modification
    * Update file reservation status
    * Log edit for audit trail

    **Exit Codes:**

    * `0` - Always allow (non-blocking hook)

    **Performance:** \~80ms average latency
  </Accordion>

  <Accordion title="💾 pre-compact: Save Critical Context" icon="floppy-disk">
    **Fires before:** Claude compacts conversation history

    **What it enables:**

    * Create memory snapshot of current context
    * Extract architecture decisions and learnings
    * Preserve critical technical details
    * Store important code patterns
    * Save pending tasks and obligations

    **Exit Codes:**

    * `0` - Allow compaction to proceed
    * `2` - Block compaction (rarely used)

    **Performance:** \~200ms average latency

    **Result:** Never lose critical context again
  </Accordion>

  <Accordion title="💬 user-prompt-submit: Alert to Urgent Messages" icon="bell">
    **Fires before:** Agent responds to user input

    **What it enables:**

    * Check for urgent unread messages
    * Display critical coordination alerts
    * Show pending acknowledgments that require attention
    * Present important file reservation conflicts
    * Alert to high-priority tasks

    **Exit Codes:**

    * `0` - Allow response (no urgent messages)
    * `2` - Block response (critical message requires acknowledgment)

    **Performance:** \~100ms average latency

    **Result:** Never miss critical coordination info
  </Accordion>

  <Accordion title="⏹️ stop: Prevent Unsafe Shutdowns" icon="hand">
    **Fires when:** User attempts to stop agent execution

    **What it enables:**

    * Check for pending critical acknowledgments
    * Warn about incomplete file reservations
    * Block shutdown if critical tasks incomplete
    * Allow graceful completion of obligations
    * Prevent orphaned locks

    **Exit Codes:**

    * `0` - Allow stop (all clear)
    * `2` - Block stop (pending critical tasks)

    **Performance:** \~90ms average latency
  </Accordion>

  <Accordion title="🧹 session-end: Clean Up Resources" icon="broom">
    **Fires when:** Session ends normally

    **What it enables:**

    * Release all file reservations automatically
    * Mark agent as offline in Coordination
    * Store final memory snapshot
    * Complete logging and audit trail
    * Clean handoff to next session

    **Exit Codes:**

    * `0` - Always allow (cleanup hook)

    **Performance:** \~110ms average latency

    **Result:** Zero orphaned file locks
  </Accordion>

  <Accordion title="👶 subagent-stop: Consolidate Learnings" icon="sitemap">
    **Fires when:** A spawned subagent completes its task

    **What it enables:**

    * Store subagent learnings to shared memory
    * Release subagent file reservations
    * Report results to parent agent
    * Update task status
    * Clean up subagent resources

    **Exit Codes:**

    * `0` - Always allow (cleanup hook)

    **Performance:** \~95ms average latency
  </Accordion>
</AccordionGroup>

***

## Real-World Use Cases

<CardGroup cols={2}>
  <Card title="Multi-Agent Development Team" icon="users" color="#8b5cf6">
    **Scenario:** 3 developers (Alice, Bob, Charlie) work on the same repository

    **How Hooks Help:**

    * Alice edits `auth.ts` → pre-edit hook reserves it
    * Bob tries to edit → blocked with clear message
    * Bob messages Alice through Coordination
    * They coordinate the changes
    * **Result:** Zero merge conflicts
  </Card>

  <Card title="Parallel Task Execution" icon="bolt" color="#f59e0b">
    **Scenario:** Main agent spawns 5 subagents for parallel workflows

    **How Hooks Help:**

    * Each subagent claims unique files via pre-edit hooks
    * Subagent-stop hooks consolidate learnings to memory
    * Session-end hooks clean up all reservations
    * **Result:** 6x faster execution, zero conflicts
  </Card>

  <Card title="Context Preservation" icon="brain" color="#3b82f6">
    **Scenario:** Long architecture discussion approaching token limit

    **How Hooks Help:**

    * Pre-compact hook fires automatically
    * Creates memory snapshot of key decisions
    * Claude compacts conversation safely
    * Architecture details preserved
    * **Result:** Never re-explain critical context
  </Card>

  <Card title="Emergency Code Freeze" icon="shield-halved" color="#ef4444">
    **Scenario:** Security issue discovered, must stop all edits

    **How Hooks Help:**

    * Admin sends urgent message to all agents
    * User-prompt hooks show alert before every response
    * Pre-edit hooks can be configured to block all edits
    * **Result:** Immediate coordination across team
  </Card>
</CardGroup>

***

## Compatible AI Assistants

ULPI Hooks works with any AI coding assistant that supports lifecycle hooks (MCP-compatible):

<Tabs>
  <Tab title="Full Support (8/8 Hooks)">
    ### ✅ Fully Supported

    These assistants support all 8 lifecycle hooks out of the box:

    * **Claude Code** - Official Anthropic IDE with complete hook support
    * **Cursor** - Full lifecycle integration including subagent hooks
    * **Windsurf** - Complete hook implementation with MCP bridge

    **Setup:** Run `ulpi setup` and hooks are installed automatically
  </Tab>

  <Tab title="Partial Support (6/8 Hooks)">
    ### ⚠️ Partial Support

    These assistants support core hooks (missing subagent-stop and pre-compact):

    * **Cline** - Session, edit, and message hooks work perfectly
    * **Roo Code** - File conflict prevention and coordination supported

    **Limitation:** Memory snapshots require manual creation
  </Tab>

  <Tab title="Coming Soon">
    ### 🚧 In Development

    We're working with these tools to add lifecycle hook support:

    * **Aider** - Hook API integration planned Q2 2025
    * **Continue** - MCP bridge development in progress
    * **GitHub Copilot** - Awaiting lifecycle event API

    **Interest?** Vote for hook support on their GitHub repos!
  </Tab>
</Tabs>

***

## Performance Metrics

Hooks are optimized for minimal latency impact:

| Hook               | Avg Latency | MCP Calls | Can Block? |
| ------------------ | ----------- | --------- | ---------- |
| session-start      | 150ms       | 3-5       | ✅ Yes      |
| pre-tool-use:edit  | 120ms       | 1-2       | ✅ Yes      |
| post-tool-use:edit | 80ms        | 1         | ❌ No       |
| pre-compact        | 200ms       | 2-3       | ✅ Yes      |
| user-prompt-submit | 100ms       | 1-2       | ✅ Yes      |
| stop               | 90ms        | 1         | ✅ Yes      |
| session-end        | 110ms       | 2-3       | ❌ No       |
| subagent-stop      | 95ms        | 1-2       | ❌ No       |

**Total overhead:** \~140ms average per hook execution
**Network calls:** 14 MCP tool calls across all hooks
**User impact:** Imperceptible in normal workflows

<Note>
  Blocking hooks (session-start, pre-edit, user-prompt, stop) only fire when necessary to prevent conflicts or ensure safety. Non-blocking hooks run asynchronously.
</Note>

***

## Automatic Setup

Getting started with Hooks takes **one command**:

<Steps>
  <Step title="Install ULPI Package">
    One package contains CLI, MCP bridge, and hooks—everything you need:

    ```bash theme={null}
    # Install globally (recommended)
    npm install -g ulpi

    # Or locally in your project
    npm install ulpi
    ```
  </Step>

  <Step title="Run Guided Setup">
    Interactive setup configures hooks automatically for all supported IDEs:

    ```bash theme={null}
    # Run the setup wizard
    ulpi setup

    # Follow the prompts:
    # 1. Enter your API token
    # 2. Select your IDE(s)
    # 3. Hooks are installed automatically
    #
    # That's it! Setup handles everything.
    ```
  </Step>

  <Step title="Restart Your IDE">
    Hooks activate automatically—zero manual configuration needed:

    ```bash theme={null}
    # Restart your IDE (Claude Code, Cursor, Windsurf, etc.)
    # Hooks will start intercepting lifecycle events
    # Check terminal for hook execution logs
    #
    # All 8 hooks are now active and coordinating your agents!
    ```
  </Step>
</Steps>

<Check>
  **Setup complete!** Your AI assistants are now coordinated through ULPI Hooks.
</Check>

***

## Integration with Other ULPI Products

Hooks supercharges other ULPI products by providing automatic integration:

<CardGroup cols={2}>
  <Card title="Coordination" icon="users" href="/coordination">
    **File Reservations:** Pre-edit hooks check and create reservations automatically

    **Messaging:** User-prompt hooks display urgent agent messages

    **Contact Policies:** Session-start hooks enforce contact policies
  </Card>

  <Card title="Memory" icon="brain" href="/memory">
    **Snapshots:** Pre-compact hooks create memory snapshots automatically

    **Context Loading:** Session-start hooks retrieve relevant memories

    **Learning Storage:** Subagent-stop hooks consolidate learnings
  </Card>

  <Card title="Tasks" icon="check-square" href="/tasks">
    **Task Updates:** Post-edit hooks update task status after file changes

    **Dependencies:** Pre-edit hooks check task dependencies before edits

    **Obligation Tracking:** Session-end hooks ensure task completion
  </Card>

  <Card title="Skills" icon="lightbulb" href="/skills">
    **Workflow Hooks:** Skills can define custom hook behaviors

    **Best Practices:** Pre-edit hooks enforce skill-defined patterns

    **Learning Loop:** Post-edit hooks improve skill recommendations
  </Card>
</CardGroup>

***

## Pricing

<Card title="FREE with Coordination + Memory" icon="gift" color="#10b981">
  Hooks are included FREE with any Coordination + Memory subscription.

  * **Starter:** \$29/month includes Hooks
  * **Professional:** \$99/month includes Hooks
  * **Enterprise:** Custom pricing includes Hooks

  No additional cost. No setup fees. No per-hook charges.
</Card>

<Note>
  **Why FREE?** Hooks maximize the value of Coordination and Memory by automating their integration. When your agents coordinate seamlessly and preserve context automatically, you get exponentially more value from both products.
</Note>

***

## Success Metrics

Teams using ULPI Hooks report:

* **Zero merge conflicts** (down from 12-20 per week)
* **100% context preservation** (vs 40% loss without hooks)
* **85% reduction** in coordination overhead
* **3x faster** multi-agent collaboration
* **60% fewer** manual file conflict resolutions

<blockquote>
  "We went from 15 merge conflicts per week to literally zero. Pre-edit hooks block conflicts before they happen. It's like magic."
  — Sarah Chen, Engineering Lead at TechCorp
</blockquote>

<blockquote>
  "Before hooks, we'd lose critical architecture decisions every time Claude compacted context. Now pre-compact hooks save everything to memory automatically. Game changer."
  — Marcus Rodriguez, Senior Architect
</blockquote>

***

## FAQ

<AccordionGroup>
  <Accordion title="Do I need to manually configure each hook?">
    No! Running `ulpi setup` automatically installs and configures all 8 hooks for your IDE. Zero manual configuration required.
  </Accordion>

  <Accordion title="Will hooks slow down my AI assistant?">
    Minimal impact. Average hook latency is \~140ms, which is imperceptible in normal workflows. Blocking hooks only fire when necessary to prevent conflicts.
  </Accordion>

  <Accordion title="What happens if a hook fails?">
    Hooks fail gracefully. If a hook times out or errors, the default behavior is to allow the operation to proceed (except for safety-critical hooks like pre-edit).
  </Accordion>

  <Accordion title="Can I disable specific hooks?">
    Yes! The ULPI config file allows you to enable/disable individual hooks. However, we recommend keeping all hooks active for full coordination benefits.
  </Accordion>

  <Accordion title="Do hooks work with local/offline AI models?">
    Hooks require network access to the ULPI API for coordination and memory features. Local-only models won't benefit from multi-agent coordination.
  </Accordion>

  <Accordion title="How do I troubleshoot hook issues?">
    Enable debug logging in your ULPI config: `ulpi config set debug=true`. Hook execution logs appear in your IDE's terminal/console.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/hooks/getting-started">
    Install hooks in 5 minutes with our guided setup wizard
  </Card>

  <Card title="Lifecycle Events" icon="diagram-project" href="/hooks/lifecycle-events">
    Deep dive into all 8 hooks and their trigger conditions
  </Card>

  <Card title="File Conflict Prevention" icon="shield-check" href="/hooks/file-conflict-prevention">
    Learn how pre-edit hooks guarantee zero merge conflicts
  </Card>

  <Card title="Use Cases" icon="book-open" href="/hooks/use-cases">
    Real-world scenarios where hooks save hours of coordination time
  </Card>
</CardGroup>