> ## 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.

# Getting Started with Hooks

> Install and configure ULPI Hooks in 5 minutes with our guided setup wizard

# Getting Started with ULPI Hooks

**One command. Automatic configuration. All 8 lifecycle hooks active in under 5 minutes.**

This guide walks you through installing ULPI Hooks and verifying they're working correctly.

***

## Prerequisites

Before installing Hooks, ensure you have:

<CardGroup cols={2}>
  <Card title="ULPI Account" icon="user">
    Sign up at [app.ulpi.io](https://app.ulpi.io) if you haven't already
  </Card>

  <Card title="API Token" icon="key">
    Generate an API token from your [API Keys](https://app.ulpi.io/api-keys) page
  </Card>

  <Card title="Coordination Subscription" icon="users">
    Hooks require an active Coordination subscription (Starter \$29/mo or higher)
  </Card>

  <Card title="Compatible IDE" icon="code">
    Claude Code, Cursor, or Windsurf installed (full support for all 8 hooks)
  </Card>
</CardGroup>

<Note>
  **Bundle Discount:** Coordination + Memory subscriptions include Hooks FREE. See [pricing](/pricing) for details.
</Note>

***

## Installation

### Step 1: Install the ULPI Package

The ULPI package includes the CLI, MCP bridge, and all 8 lifecycle hooks in one install:

<CodeGroup>
  ```bash Global (Recommended) theme={null}
  # Install globally for system-wide access
  npm install -g ulpi

  # Verify installation
  ulpi --version
  ```

  ```bash Local (Project-specific) theme={null}
  # Install in your project directory
  npm install ulpi

  # Verify installation
  npx ulpi --version
  ```
</CodeGroup>

<Check>
  **Why global?** Global installation makes the `ulpi` command available everywhere, simplifying setup across multiple projects.
</Check>

***

### Step 2: Run the Guided Setup Wizard

The setup wizard automatically detects your installed IDEs and configures hooks for each:

```bash theme={null}
ulpi setup
```

<Steps>
  <Step title="Enter API Token">
    When prompted, paste your ULPI API token:

    ```
    ? Enter your ULPI API token: ulpi_sk_...
    ✓ Token validated successfully
    ```

    <Tip>
      Get your API token from [app.ulpi.io/api-keys](https://app.ulpi.io/api-keys)
    </Tip>
  </Step>

  <Step title="Select IDEs">
    The wizard scans your system and lists detected IDEs:

    ```
    ? Select IDEs to configure hooks for: (Use arrow keys and space to select)
    ◉ Claude Code
    ◉ Cursor
    ◯ Windsurf (not detected)
    ◉ Cline (VS Code extension)
    ```

    Select all IDEs you want to use with ULPI Hooks.
  </Step>

  <Step title="Configure Hook Settings">
    Choose your hook behavior preferences:

    ```
    ? Enable all 8 hooks by default? (Y/n) Y
    ? Auto-reserve files on first edit? (Y/n) Y
    ? Block unsafe shutdowns? (Y/n) Y
    ? Debug logging enabled? (y/N) N
    ```

    **Recommended:** Accept defaults (Yes for all except debug logging)
  </Step>

  <Step title="Automatic Configuration">
    The wizard creates config files for each selected IDE:

    ```
    ✓ Created ~/.ulpi/config.json
    ✓ Configured Claude Code hooks at ~/.claude-code/hooks/
    ✓ Configured Cursor hooks at ~/.cursor/hooks/
    ✓ Configured Cline hooks at ~/.vscode/extensions/
    ✓ MCP bridge configured

    🎉 Setup complete! Restart your IDEs to activate hooks.
    ```
  </Step>
</Steps>

<Warning>
  **Manual Setup Not Required:** The wizard handles all configuration automatically. You don't need to edit config files manually unless customizing behavior.
</Warning>

***

### Step 3: Restart Your IDE

For hooks to take effect, restart each IDE you configured:

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    # Close all Claude Code windows
    # Relaunch Claude Code

    # Or via CLI:
    claude-code --restart
    ```
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    # Close all Cursor windows
    # Relaunch Cursor

    # Or use Command Palette:
    # Cmd+Shift+P → "Developer: Reload Window"
    ```
  </Tab>

  <Tab title="Windsurf">
    ```bash theme={null}
    # Close all Windsurf windows
    # Relaunch Windsurf
    ```
  </Tab>

  <Tab title="Cline">
    ```bash theme={null}
    # Reload VS Code window:
    # Cmd+Shift+P → "Developer: Reload Window"

    # Or restart VS Code completely
    ```
  </Tab>
</Tabs>

***

## Verify Hooks Are Working

After restarting your IDE, verify hooks are active:

### 1. Check Hook Status

Run the status command to see active hooks:

```bash theme={null}
ulpi hooks status
```

**Expected output:**

```
✓ ULPI Hooks Status

IDE: Claude Code
├─ ✓ session-start (active)
├─ ✓ pre-tool-use:edit (active)
├─ ✓ post-tool-use:edit (active)
├─ ✓ pre-compact (active)
├─ ✓ user-prompt-submit (active)
├─ ✓ stop (active)
├─ ✓ session-end (active)
└─ ✓ subagent-stop (active)

All 8 hooks are active and healthy.
Last hook execution: 2 minutes ago (pre-tool-use:edit)
```

***

### 2. Test Session Start Hook

Open your IDE and start a new chat session. You should see a coordination dashboard:

<CodeGroup>
  ```plaintext Expected Output theme={null}
  ╔══════════════════════════════════════════════════════════╗
  ║  🤖 ULPI Coordination Dashboard                          ║
  ╠══════════════════════════════════════════════════════════╣
  ║  Agent: Claude-Code-YourName                             ║
  ║  Status: Online                                          ║
  ║  Project: my-project                                     ║
  ║                                                          ║
  ║  📬 Unread Messages: 0                                   ║
  ║  🔒 Active File Reservations: 3                          ║
  ║  ├─ auth.ts (reserved by Claude-Cursor-Alice)            ║
  ║  ├─ database.ts (reserved by Claude-Code-Bob)            ║
  ║  └─ api.routes.ts (reserved by you, expires in 2h)       ║
  ║                                                          ║
  ║  💾 Memories Loaded: 47                                  ║
  ║  ⚡ Session Started: 2024-01-15 10:30 AM                 ║
  ╚══════════════════════════════════════════════════════════╝
  ```
</CodeGroup>

<Check>
  **If you see this dashboard:** Session-start hook is working! ✅
</Check>

***

### 3. Test Pre-Edit Hook (File Conflict Prevention)

Try editing a file that another agent has reserved:

<Steps>
  <Step title="Identify Reserved File">
    From the coordination dashboard, note a file reserved by another agent (e.g., `auth.ts` reserved by Alice)
  </Step>

  <Step title="Attempt to Edit">
    In your IDE, try to modify that file. The pre-edit hook should block you:

    ```plaintext theme={null}
    ⛔ Edit Blocked by ULPI Hooks

    File: src/auth.ts
    Reserved by: Claude-Cursor-Alice
    Reservation mode: Exclusive
    Expires: 2024-01-15 12:30 PM

    Reason: This file is currently being edited by another agent.

    Options:
    1. Message Alice to coordinate changes
    2. Wait for reservation to expire (2 hours)
    3. Request emergency override (requires approval)

    [Message Alice] [Wait] [Cancel]
    ```
  </Step>

  <Step title="Verify Blocking">
    The edit should be prevented, and you should see the blocking message.

    <Check>
      **If editing was blocked:** Pre-edit hook is working! ✅
    </Check>
  </Step>
</Steps>

***

### 4. Test File Reservation (Auto-Reserve)

Edit a file that's NOT reserved by anyone:

<Steps>
  <Step title="Edit Unreserved File">
    Open and modify any file not shown in the active reservations list
  </Step>

  <Step title="Check Reservation">
    After saving, run:

    ```bash theme={null}
    ulpi coordination list-reservations
    ```

    You should see your new reservation:

    ```
    📋 File Reservations

    You (Claude-Code-YourName):
    ├─ src/utils.ts (mode: shared, expires: 2h)
    └─ src/api.routes.ts (mode: shared, expires: 2h)

    Other Agents:
    ├─ src/auth.ts (Claude-Cursor-Alice, exclusive, expires: 1h 45m)
    └─ src/database.ts (Claude-Code-Bob, shared, expires: 30m)
    ```
  </Step>

  <Step title="Verify Auto-Reservation">
    <Check>
      **If your file appears in the list:** Auto-reservation is working! ✅
    </Check>
  </Step>
</Steps>

***

### 5. Test User-Prompt Hook (Message Alerts)

Have another agent (or yourself from another IDE) send you an urgent message:

<Steps>
  <Step title="Send Urgent Message">
    From another IDE or via CLI:

    ```bash theme={null}
    ulpi coordination send-message \
      --to "Claude-Code-YourName" \
      --subject "Security issue in auth.ts" \
      --priority urgent \
      --body "Found SQL injection vulnerability in login function"
    ```
  </Step>

  <Step title="Submit Prompt">
    In your IDE, type any message to your AI assistant and press Enter
  </Step>

  <Step title="Check for Alert">
    Before the AI responds, you should see an urgent message alert:

    ```plaintext theme={null}
    ⚠️  URGENT COORDINATION MESSAGE

    From: Claude-Cursor-Alice
    Subject: Security issue in auth.ts
    Priority: Urgent
    Received: 2 minutes ago

    Message:
    Found SQL injection vulnerability in login function in src/auth.ts line 45.
    Please review before making any auth-related changes.

    [View Full Message] [Acknowledge] [Ignore]
    ```
  </Step>

  <Step title="Verify Alert Display">
    <Check>
      **If you see the alert:** User-prompt hook is working! ✅
    </Check>
  </Step>
</Steps>

***

## Hook Configuration

All hooks are configured in `~/.ulpi/config.json`. You can customize behavior:

```json ~/.ulpi/config.json theme={null}
{
  "apiToken": "ulpi_sk_...",
  "apiUrl": "https://api.ulpi.io",
  "hooks": {
    "enabled": true,
    "sessionStart": {
      "enabled": true,
      "showDashboard": true,
      "loadMemories": true
    },
    "preEdit": {
      "enabled": true,
      "autoReserve": true,
      "defaultMode": "shared",
      "blockConflicts": true
    },
    "postEdit": {
      "enabled": true,
      "showObligations": true,
      "updateTasks": true
    },
    "preCompact": {
      "enabled": true,
      "createSnapshot": true,
      "minImportance": 0.5
    },
    "userPrompt": {
      "enabled": true,
      "showUrgentMessages": true,
      "requireAck": true
    },
    "stop": {
      "enabled": true,
      "blockUnsafe": true,
      "warnPendingAcks": true
    },
    "sessionEnd": {
      "enabled": true,
      "releaseReservations": true,
      "createSnapshot": true
    },
    "subagentStop": {
      "enabled": true,
      "consolidateLearnings": true
    }
  },
  "debug": false
}
```

### Common Customizations

<AccordionGroup>
  <Accordion title="Disable specific hooks">
    Set `"enabled": false` for any hook you don't want:

    ```json theme={null}
    "preCompact": {
      "enabled": false  // Disable memory snapshots
    }
    ```
  </Accordion>

  <Accordion title="Change default reservation mode">
    Switch between `shared` (multiple readers) and `exclusive` (one writer):

    ```json theme={null}
    "preEdit": {
      "defaultMode": "exclusive"  // Lock files exclusively
    }
    ```
  </Accordion>

  <Accordion title="Enable debug logging">
    See detailed hook execution logs:

    ```json theme={null}
    "debug": true
    ```

    Logs appear in your IDE's terminal/console.
  </Accordion>

  <Accordion title="Adjust memory snapshot threshold">
    Control which memories are saved during compaction:

    ```json theme={null}
    "preCompact": {
      "minImportance": 0.7  // Only save high-importance memories
    }
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  **Restart Required:** After changing config, restart your IDE for changes to take effect.
</Warning>

***

## Troubleshooting

### Hooks not activating after restart

**Symptoms:** No coordination dashboard on session start, edits not checking reservations

**Solutions:**

1. Verify installation: `ulpi hooks status`
2. Check API token is valid: `ulpi auth verify`
3. Ensure Coordination subscription is active
4. Check hook config file exists: `ls ~/.ulpi/config.json`
5. Enable debug logging and check for errors

***

### "Token invalid" error during setup

**Symptoms:** Setup wizard rejects your API token

**Solutions:**

1. Generate a new token at [app.ulpi.io/api-keys](https://app.ulpi.io/api-keys)
2. Ensure token has full permissions (not read-only)
3. Copy token carefully (no extra spaces)
4. Try manual configuration: `ulpi config set apiToken=<token>`

***

### Pre-edit hook not blocking conflicts

**Symptoms:** You can edit files reserved by other agents

**Solutions:**

1. Check `preEdit.blockConflicts` is `true` in config
2. Verify you're connected to Coordination: `ulpi coordination status`
3. Ensure reservation exists: `ulpi coordination list-reservations`
4. Check debug logs for hook execution errors

***

### Session-start hook too slow

**Symptoms:** IDE takes 5+ seconds to start sessions

**Solutions:**

1. Disable dashboard display: `sessionStart.showDashboard = false`
2. Don't load all memories: `sessionStart.loadMemories = false`
3. Check network latency to ULPI API
4. Ensure you're on a stable internet connection

***

### Hooks work in one IDE but not another

**Symptoms:** Cursor hooks work, but Claude Code hooks don't (or vice versa)

**Solutions:**

1. Run `ulpi setup` again and select all IDEs
2. Check IDE-specific config files were created
3. Verify IDE supports lifecycle hooks (see compatibility)
4. Update IDE to latest version

***

## Advanced: Manual Hook Installation

If the guided setup doesn't work, you can install hooks manually:

<Steps>
  <Step title="Create Config Directory">
    ```bash theme={null}
    mkdir -p ~/.ulpi
    ```
  </Step>

  <Step title="Create Config File">
    ```bash theme={null}
    cat > ~/.ulpi/config.json << EOF
    {
      "apiToken": "your-token-here",
      "apiUrl": "https://api.ulpi.io",
      "hooks": {
        "enabled": true
      }
    }
    EOF
    ```
  </Step>

  <Step title="Install IDE-Specific Hooks">
    <Tabs>
      <Tab title="Claude Code">
        ```bash theme={null}
        # Create hooks directory
        mkdir -p ~/.claude-code/hooks

        # Symlink ULPI hooks
        ln -s $(npm root -g)/ulpi/hooks/* ~/.claude-code/hooks/
        ```
      </Tab>

      <Tab title="Cursor">
        ```bash theme={null}
        # Create hooks directory
        mkdir -p ~/.cursor/hooks

        # Symlink ULPI hooks
        ln -s $(npm root -g)/ulpi/hooks/* ~/.cursor/hooks/
        ```
      </Tab>

      <Tab title="VS Code (Cline)">
        ```bash theme={null}
        # Find Cline extension directory
        CLINE_DIR=~/.vscode/extensions/saoudrizwan.claude-dev-*

        # Create hooks directory
        mkdir -p $CLINE_DIR/hooks

        # Symlink ULPI hooks
        ln -s $(npm root -g)/ulpi/hooks/* $CLINE_DIR/hooks/
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify Installation">
    ```bash theme={null}
    ulpi hooks status
    ```
  </Step>
</Steps>

***

## Next Steps

Now that hooks are installed and working, explore their capabilities:

<CardGroup cols={2}>
  <Card title="Lifecycle Events Deep Dive" icon="diagram-project" href="/hooks/lifecycle-events">
    Learn exactly when each hook fires and what MCP tools it uses
  </Card>

  <Card title="File Conflict Prevention" icon="shield-check" href="/hooks/file-conflict-prevention">
    Master the pre-edit hook and achieve zero merge conflicts
  </Card>

  <Card title="Memory Integration" icon="brain" href="/hooks/memory-integration">
    Preserve context automatically with pre-compact memory snapshots
  </Card>

  <Card title="Real-World Use Cases" icon="book-open" href="/hooks/use-cases">
    See how teams use hooks to coordinate 3, 5, or 10+ agents
  </Card>
</CardGroup>