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

# Assistant Compatibility

> Setup guides for Claude Code, Cursor, Windsurf, Cline, and other AI coding assistants

# AI Assistant Compatibility

**ULPI Hooks works with any AI coding assistant that supports lifecycle hooks.**

This guide provides setup instructions for each supported assistant, compatibility details, and troubleshooting tips.

***

## Compatibility Overview

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

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

    <CardGroup cols={3}>
      <Card title="Claude Code" icon="code" color="#8b5cf6">
        **Anthropic's official IDE**

        * All 8 hooks supported
        * Native integration
        * Zero configuration
        * Best performance
      </Card>

      <Card title="Cursor" icon="cursor-click" color="#3b82f6">
        **AI-first code editor**

        * All 8 hooks supported
        * Excellent performance
        * Auto-detects hooks
        * Active development
      </Card>

      <Card title="Windsurf" icon="wind" color="#10b981">
        **Collaborative AI editor**

        * All 8 hooks supported
        * MCP-native design
        * Fast hook execution
        * Growing ecosystem
      </Card>
    </CardGroup>

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

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

    These assistants support core hooks but miss some advanced ones:

    <CardGroup cols={2}>
      <Card title="Cline" icon="puzzle-piece" color="#f59e0b">
        **VS Code extension**

        **Supported hooks (6/8):**

        * ✅ session-start
        * ✅ pre-tool-use:edit
        * ✅ post-tool-use:edit
        * ✅ user-prompt-submit
        * ✅ stop
        * ✅ session-end

        **Missing:**

        * ❌ pre-compact (manual snapshots required)
        * ❌ subagent-stop (no subagent support yet)
      </Card>

      <Card title="Roo Code" icon="kangaroo" color="#ef4444">
        **Terminal-based AI assistant**

        **Supported hooks (6/8):**

        * ✅ session-start
        * ✅ pre-tool-use:edit
        * ✅ post-tool-use:edit
        * ✅ user-prompt-submit
        * ✅ stop
        * ✅ session-end

        **Missing:**

        * ❌ pre-compact (context model different)
        * ❌ subagent-stop (no subagent support)
      </Card>
    </CardGroup>

    **Limitation:** Memory preservation and subagent coordination unavailable
  </Tab>

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

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

    <CardGroup cols={3}>
      <Card title="Aider" icon="terminal" color="#6b7280">
        **CLI AI pair programmer**

        **Status:** Hook API integration planned Q2 2025

        **Interest:** Vote on [GitHub Issue #123](https://github.com/paul-gauthier/aider/issues/123)
      </Card>

      <Card title="Continue" icon="play-circle" color="#6b7280">
        **VS Code AI assistant**

        **Status:** MCP bridge in development

        **Interest:** Track [GitHub PR #456](https://github.com/continuedev/continue/pull/456)
      </Card>

      <Card title="GitHub Copilot" icon="github" color="#6b7280">
        **GitHub's AI assistant**

        **Status:** Awaiting lifecycle event API

        **Interest:** [GitHub Discussion #789](https://github.com/github/copilot/discussions/789)
      </Card>
    </CardGroup>

    **Want your assistant supported?** [Request support](https://ulpi.io/assistant-support-request)
  </Tab>
</Tabs>

***

## Claude Code Setup

### Installation

**Prerequisites:**

* Claude Code installed (version ≥ 1.0.0)
* ULPI API token
* Coordination subscription active

**Setup Steps:**

<Steps>
  <Step title="Install ULPI Package">
    ```bash theme={null}
    npm install -g ulpi
    ```
  </Step>

  <Step title="Run Guided Setup">
    ```bash theme={null}
    ulpi setup
    ```

    Select "Claude Code" when prompted.
  </Step>

  <Step title="Restart Claude Code">
    ```bash theme={null}
    # Close all Claude Code windows and relaunch
    # Or via CLI:
    claude-code --restart
    ```
  </Step>

  <Step title="Verify Hooks Active">
    Open Claude Code and start a new chat. You should see:

    ```plaintext theme={null}
    ╔══════════════════════════════════════════╗
    ║  🤖 ULPI Coordination Dashboard          ║
    ╠══════════════════════════════════════════╣
    ║  Agent: Claude-Code-YourName             ║
    ║  Status: Online                          ║
    ║  Hooks: 8/8 active ✓                     ║
    ╚══════════════════════════════════════════╝
    ```
  </Step>
</Steps>

***

### Configuration

Claude Code hooks are configured in `~/.claude-code/hooks/ulpi.config.json`:

```json theme={null}
{
  "apiToken": "ulpi_sk_...",
  "apiUrl": "https://api.ulpi.io",
  "hooks": {
    "sessionStart": { "enabled": true },
    "preEdit": { "enabled": true, "autoReserve": true },
    "postEdit": { "enabled": true },
    "preCompact": { "enabled": true, "createSnapshot": true },
    "userPrompt": { "enabled": true },
    "stop": { "enabled": true },
    "sessionEnd": { "enabled": true },
    "subagentStop": { "enabled": true }
  }
}
```

***

### Performance

Claude Code has the **best hook performance**:

| Hook          | Latency     | Notes                        |
| ------------- | ----------- | ---------------------------- |
| session-start | \~130ms     | Fastest (native integration) |
| pre-edit      | \~100ms     | Fastest (local caching)      |
| pre-compact   | \~180ms     | Native compaction API        |
| Overall       | \~115ms avg | Best-in-class                |

***

### Troubleshooting

<AccordionGroup>
  <Accordion title="Hooks not showing on session start">
    **Solution:**

    1. Check config exists: `ls ~/.claude-code/hooks/ulpi.config.json`
    2. Verify API token: `ulpi auth verify`
    3. Check logs: `claude-code --debug-hooks`
    4. Reinstall: `ulpi setup --force`
  </Accordion>

  <Accordion title="Pre-compact hook not firing">
    **Solution:**
    Claude Code uses a different compaction trigger. Enable debug logging:

    ```json theme={null}
    { "debug": true, "hooks": { "preCompact": { "verbose": true } } }
    ```

    Watch logs for compaction events.
  </Accordion>
</AccordionGroup>

***

## Cursor Setup

### Installation

**Prerequisites:**

* Cursor installed (version ≥ 0.30.0)
* ULPI API token
* Coordination subscription active

**Setup Steps:**

<Steps>
  <Step title="Install ULPI Package">
    ```bash theme={null}
    npm install -g ulpi
    ```
  </Step>

  <Step title="Run Guided Setup">
    ```bash theme={null}
    ulpi setup
    ```

    Select "Cursor" when prompted.
  </Step>

  <Step title="Reload Cursor Window">
    In Cursor:

    * Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
    * Type "Developer: Reload Window"
    * Press Enter
  </Step>

  <Step title="Verify Hooks Active">
    Open Cursor composer and check bottom-right status bar:

    ```plaintext theme={null}
    ULPI Hooks: 8/8 active ✓
    ```
  </Step>
</Steps>

***

### Configuration

Cursor hooks are configured in `~/.cursor/hooks/ulpi.config.json`:

```json theme={null}
{
  "apiToken": "ulpi_sk_...",
  "apiUrl": "https://api.ulpi.io",
  "hooks": {
    // Same as Claude Code config
  },
  "cursor": {
    // Cursor-specific settings
    "composerIntegration": true,  // Show hooks in composer
    "statusBarIcon": true          // Show status in status bar
  }
}
```

***

### Cursor-Specific Features

**Composer Integration:**

When using Cursor's composer mode, hooks integrate seamlessly:

```plaintext theme={null}
┌─────────────────────────────────────────┐
│  Cursor Composer                        │
├─────────────────────────────────────────┤
│  > Implement OAuth login                │
│                                         │
│  🔒 ULPI: auth/login.ts reserved by     │
│     Alice. Coordinate before editing?   │
│                                         │
│  [Proceed] [Message Alice] [Cancel]     │
└─────────────────────────────────────────┘
```

**Multi-file edits:**

Cursor can edit multiple files at once. Pre-edit hook checks ALL files:

```plaintext theme={null}
⚠️  Multi-File Edit Check

Files to edit: 5
├─ src/auth/login.ts (available ✓)
├─ src/auth/logout.ts (available ✓)
├─ src/auth/middleware.ts (RESERVED by Alice ⛔)
├─ tests/auth.test.ts (available ✓)
└─ docs/auth.md (available ✓)

1 file conflict detected. Coordinate with Alice?

[Edit Available Files] [Message Alice] [Cancel All]
```

***

### Performance

Cursor has **excellent hook performance**:

| Hook          | Latency     | Notes                       |
| ------------- | ----------- | --------------------------- |
| session-start | \~145ms     | Fast startup                |
| pre-edit      | \~110ms     | Batch checks for multi-file |
| pre-compact   | \~190ms     | Efficient compaction        |
| Overall       | \~120ms avg | Very good                   |

***

### Troubleshooting

<AccordionGroup>
  <Accordion title="Status bar not showing hooks">
    **Solution:**
    Enable status bar icon in config:

    ```json theme={null}
    { "cursor": { "statusBarIcon": true } }
    ```

    Then reload window.
  </Accordion>

  <Accordion title="Composer ignoring file reservations">
    **Solution:**
    Ensure composer integration enabled:

    ```json theme={null}
    { "cursor": { "composerIntegration": true } }
    ```
  </Accordion>
</AccordionGroup>

***

## Windsurf Setup

### Installation

**Prerequisites:**

* Windsurf installed (version ≥ 1.0.0)
* ULPI API token
* Coordination subscription active

**Setup Steps:**

<Steps>
  <Step title="Install ULPI Package">
    ```bash theme={null}
    npm install -g ulpi
    ```
  </Step>

  <Step title="Run Guided Setup">
    ```bash theme={null}
    ulpi setup
    ```

    Select "Windsurf" when prompted.
  </Step>

  <Step title="Restart Windsurf">
    Close and relaunch Windsurf.
  </Step>

  <Step title="Verify Hooks Active">
    Check Windsurf's MCP panel:

    ```plaintext theme={null}
    MCP Servers:
    ├─ ULPI Coordination ✓
    ├─ ULPI Memory ✓
    └─ ULPI Hooks (8/8 active) ✓
    ```
  </Step>
</Steps>

***

### Configuration

Windsurf hooks are configured in `~/.windsurf/mcp-servers.json`:

```json theme={null}
{
  "mcpServers": {
    "ulpi-hooks": {
      "command": "ulpi-mcp",
      "args": ["hooks"],
      "env": {
        "ULPI_API_TOKEN": "ulpi_sk_...",
        "ULPI_API_URL": "https://api.ulpi.io"
      }
    }
  }
}
```

***

### Windsurf-Specific Features

**Collaborative Hooks:**

Windsurf's real-time collaboration works with hooks:

```plaintext theme={null}
👥 Collaboration Session

Participants:
- You (Windsurf-Alice) 🟢
- Bob (Windsurf-Bob) 🟢
- Charlie (Windsurf-Charlie) 🟢

File Reservations:
- auth.ts: Alice (exclusive)
- api.ts: Bob (shared)
- tests.ts: Charlie (shared)

All participants see live reservation updates.
```

***

### Performance

Windsurf has **excellent hook performance**:

| Hook          | Latency     | Notes                  |
| ------------- | ----------- | ---------------------- |
| session-start | \~140ms     | MCP-native integration |
| pre-edit      | \~105ms     | Very fast              |
| pre-compact   | \~185ms     | Efficient              |
| Overall       | \~118ms avg | Excellent              |

***

## Cline (VS Code Extension) Setup

### Installation

**Prerequisites:**

* VS Code installed
* Cline extension installed from marketplace
* ULPI API token

**Setup Steps:**

<Steps>
  <Step title="Install Cline Extension">
    In VS Code:

    1. Press `Cmd+Shift+X` (Extensions)
    2. Search "Cline"
    3. Click "Install"
  </Step>

  <Step title="Install ULPI Package">
    ```bash theme={null}
    npm install -g ulpi
    ```
  </Step>

  <Step title="Run Setup for Cline">
    ```bash theme={null}
    ulpi setup
    ```

    Select "Cline (VS Code)" when prompted.
  </Step>

  <Step title="Reload VS Code">
    * Press `Cmd+Shift+P` → "Developer: Reload Window"
  </Step>

  <Step title="Verify Hooks">
    Open Cline panel. You should see:

    ```plaintext theme={null}
    ULPI Hooks: 6/8 active ⚠️
    (Missing: pre-compact, subagent-stop)
    ```
  </Step>
</Steps>

***

### Limitations

Cline supports **6 out of 8 hooks**:

**✅ Supported:**

* session-start
* pre-tool-use:edit
* post-tool-use:edit
* user-prompt-submit
* stop
* session-end

**❌ Not Supported:**

* pre-compact (Cline doesn't expose compaction events)
* subagent-stop (Cline doesn't support subagents)

**Workaround for pre-compact:**
Manually create memory snapshots:

```bash theme={null}
# Create snapshot before long break
ulpi memory snapshot --create
```

***

## Feature Comparison

| Feature                | Claude Code | Cursor      | Windsurf    | Cline        | Roo Code  |
| ---------------------- | ----------- | ----------- | ----------- | ------------ | --------- |
| **Hooks Supported**    | 8/8 ✅       | 8/8 ✅       | 8/8 ✅       | 6/8 ⚠️       | 6/8 ⚠️    |
| **session-start**      | ✅           | ✅           | ✅           | ✅            | ✅         |
| **pre-edit**           | ✅           | ✅           | ✅           | ✅            | ✅         |
| **post-edit**          | ✅           | ✅           | ✅           | ✅            | ✅         |
| **pre-compact**        | ✅           | ✅           | ✅           | ❌            | ❌         |
| **user-prompt**        | ✅           | ✅           | ✅           | ✅            | ✅         |
| **stop**               | ✅           | ✅           | ✅           | ✅            | ✅         |
| **session-end**        | ✅           | ✅           | ✅           | ✅            | ✅         |
| **subagent-stop**      | ✅           | ✅           | ✅           | ❌            | ❌         |
| **Avg Latency**        | 115ms       | 120ms       | 118ms       | 130ms        | 140ms     |
| **Auto-Setup**         | ✅           | ✅           | ✅           | ⚠️ Manual    | ⚠️ Manual |
| **Native Integration** | ✅ Best      | ✅ Excellent | ✅ Excellent | ⚠️ Extension | ⚠️ CLI    |

***

## Switching Between Assistants

**Hooks work across assistants.** You can use different assistants for different tasks:

**Example:**

* **Morning:** Use Claude Code for architecture planning
  * session-start loads memories
  * pre-compact saves decisions

* **Afternoon:** Switch to Cursor for implementation
  * session-start loads same memories
  * pre-edit reserves files

* **Evening:** Review with Windsurf in collaboration mode
  * All file reservations visible to collaborators

**All assistants share:**

* Same ULPI Memory
* Same Coordination state
* Same file reservations
* Same agent messages

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use best assistant for each task" icon="puzzle-piece">
    **Recommendation:**

    * **Architecture/Planning:** Claude Code (best context preservation)
    * **Feature Implementation:** Cursor (excellent composer mode)
    * **Team Collaboration:** Windsurf (real-time collaboration)
    * **Quick Edits:** Cline (lightweight, VS Code integrated)
  </Accordion>

  <Accordion title="Maintain consistent agent identity" icon="id-card">
    **Recommendation:** Use same agent name across assistants

    **Config:**

    ```json theme={null}
    {
      "agentName": "YourName",  // Same for all assistants
      "agentPrefix": "auto"      // Auto-detects assistant type
    }
    ```

    **Result:**

    * `Claude-Code-YourName` (when using Claude Code)
    * `Cursor-YourName` (when using Cursor)
    * `Windsurf-YourName` (when using Windsurf)

    **Benefit:** Team knows it's you regardless of assistant
  </Accordion>

  <Accordion title="Sync config across assistants" icon="sync">
    **Recommendation:** Use global config for consistency

    **Setup:**

    ```bash theme={null}
    # Use global config (applies to all assistants)
    ulpi config set --global minImportance=0.5
    ulpi config set --global autoReserve=true
    ```

    **Override per assistant if needed:**

    ```bash theme={null}
    # Cursor-specific setting
    ulpi config set --assistant cursor composerIntegration=true
    ```
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

### General Issues

<AccordionGroup>
  <Accordion title="Hooks not working after setup">
    **Diagnosis:**

    ```bash theme={null}
    # Check hook status
    ulpi hooks status

    # Check configuration
    ulpi config list

    # Verify API token
    ulpi auth verify
    ```

    **Solutions:**

    1. Ensure assistant is restarted after setup
    2. Check API token is valid
    3. Verify Coordination subscription active
    4. Try re-running setup: `ulpi setup --force`
  </Accordion>

  <Accordion title="Some hooks work, others don't">
    **Diagnosis:**

    ```bash theme={null}
    # List hook execution history
    ulpi hooks history --last 10
    ```

    **Solutions:**

    1. Check which hooks are failing
    2. Enable debug mode: `ulpi config set debug=true`
    3. Check assistant version (may need update)
    4. Review assistant-specific limitations
  </Accordion>

  <Accordion title="Hook latency too high">
    **Diagnosis:**

    ```bash theme={null}
    # Check hook performance
    ulpi hooks performance
    ```

    **Solutions:**

    1. Check network latency to ULPI API
    2. Enable caching: `ulpi config set cacheEnabled=true`
    3. Reduce session-start memory loading: `min Importance=0.7`
    4. Disable non-critical hooks
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/hooks/getting-started">
    Complete setup guide with verification steps
  </Card>

  <Card title="Lifecycle Events" icon="diagram-project" href="/hooks/lifecycle-events">
    Learn when each hook fires and what it enables
  </Card>

  <Card title="Performance Optimization" icon="gauge" href="/hooks/performance">
    Optimize hook performance for your workflow
  </Card>

  <Card title="Request Assistant Support" icon="hand-point-up" href="https://ulpi.io/assistant-support-request">
    Want your favorite assistant supported? Let us know!
  </Card>
</CardGroup>