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

Full Support (8/8 Hooks)
Partial Support (6/8 Hooks)
Coming Soon

✅ Fully Compatible Assistants

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

Claude Code

Anthropic’s official IDE

All 8 hooks supported
Native integration
Zero configuration
Best performance

Cursor

AI-first code editor

All 8 hooks supported
Excellent performance
Auto-detects hooks
Active development

Windsurf

Collaborative AI editor

All 8 hooks supported
MCP-native design
Fast hook execution
Growing ecosystem

Setup: Run ulpi setup and hooks install automatically

Claude Code Setup

Installation

Prerequisites:

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

Setup Steps:

Install ULPI Package

npm install -g ulpi

Run Guided Setup

ulpi setup

Select “Claude Code” when prompted.

Restart Claude Code

# Close all Claude Code windows and relaunch
# Or via CLI:
claude-code --restart

Verify Hooks Active

Open Claude Code and start a new chat. You should see:

╔══════════════════════════════════════════╗
║  🤖 ULPI Coordination Dashboard          ║
╠══════════════════════════════════════════╣
║  Agent: Claude-Code-YourName             ║
║  Status: Online                          ║
║  Hooks: 8/8 active ✓                     ║
╚══════════════════════════════════════════╝

Configuration

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

{
  "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

Hooks not showing on session start

Solution:

Check config exists: ls ~/.claude-code/hooks/ulpi.config.json
Verify API token: ulpi auth verify
Check logs: claude-code --debug-hooks
Reinstall: ulpi setup --force

Pre-compact hook not firing

Solution: Claude Code uses a different compaction trigger. Enable debug logging:

{ "debug": true, "hooks": { "preCompact": { "verbose": true } } }

Watch logs for compaction events.

Cursor Setup

Installation

Prerequisites:

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

Setup Steps:

Install ULPI Package

npm install -g ulpi

Run Guided Setup

ulpi setup

Select “Cursor” when prompted.

Reload Cursor Window

In Cursor:

Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
Type “Developer: Reload Window”
Press Enter

Verify Hooks Active

Open Cursor composer and check bottom-right status bar:

ULPI Hooks: 8/8 active ✓

Configuration

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

{
  "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:

┌─────────────────────────────────────────┐
│  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:

⚠️  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

Status bar not showing hooks

Solution: Enable status bar icon in config:

{ "cursor": { "statusBarIcon": true } }

Then reload window.

Composer ignoring file reservations

Solution: Ensure composer integration enabled:

{ "cursor": { "composerIntegration": true } }

Windsurf Setup

Installation

Prerequisites:

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

Setup Steps:

Install ULPI Package

npm install -g ulpi

Run Guided Setup

ulpi setup

Select “Windsurf” when prompted.

Restart Windsurf

Close and relaunch Windsurf.

Verify Hooks Active

Check Windsurf’s MCP panel:

MCP Servers:
├─ ULPI Coordination ✓
├─ ULPI Memory ✓
└─ ULPI Hooks (8/8 active) ✓

Configuration

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

{
  "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:

👥 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:

Install Cline Extension

In VS Code:

Press Cmd+Shift+X (Extensions)
Search “Cline”
Click “Install”

Install ULPI Package

npm install -g ulpi

Run Setup for Cline

ulpi setup

Select “Cline (VS Code)” when prompted.

Reload VS Code

Press Cmd+Shift+P → “Developer: Reload Window”

Verify Hooks

Open Cline panel. You should see:

ULPI Hooks: 6/8 active ⚠️
(Missing: pre-compact, subagent-stop)

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:

# 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

Use best assistant for each task

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)

Maintain consistent agent identity

Recommendation: Use same agent name across assistantsConfig:

{
  "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

Sync config across assistants

Recommendation: Use global config for consistencySetup:

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

# Cursor-specific setting
ulpi config set --assistant cursor composerIntegration=true

Troubleshooting

General Issues

Hooks not working after setup

Diagnosis:

# Check hook status
ulpi hooks status

# Check configuration
ulpi config list

# Verify API token
ulpi auth verify

Solutions:

Ensure assistant is restarted after setup
Check API token is valid
Verify Coordination subscription active
Try re-running setup: ulpi setup --force

Some hooks work, others don't

Diagnosis:

# List hook execution history
ulpi hooks history --last 10

Solutions:

Check which hooks are failing
Enable debug mode: ulpi config set debug=true
Check assistant version (may need update)
Review assistant-specific limitations

Hook latency too high

Diagnosis:

# Check hook performance
ulpi hooks performance

Solutions:

Check network latency to ULPI API
Enable caching: ulpi config set cacheEnabled=true
Reduce session-start memory loading: min Importance=0.7
Disable non-critical hooks

Next Steps

Getting Started

Complete setup guide with verification steps

Lifecycle Events

Learn when each hook fires and what it enables

Performance Optimization

Optimize hook performance for your workflow

Request Assistant Support

Want your favorite assistant supported? Let us know!

Getting Started

Documentation

Skills

Coordination

Memory

Hooks

Tasks

Help & Security

​AI Assistant Compatibility

​Compatibility Overview

​✅ Fully Compatible Assistants

Claude Code

Cursor

Windsurf

​Claude Code Setup

​Installation

​Configuration

​Performance

​Troubleshooting

​Cursor Setup

​Installation

​Configuration

​Cursor-Specific Features

​Performance

​Troubleshooting

​Windsurf Setup

​Installation

​Configuration

​Windsurf-Specific Features

​Performance

​Cline (VS Code Extension) Setup

​Installation

​Limitations

​Feature Comparison

​Switching Between Assistants

​Best Practices

​Troubleshooting

​General Issues

​Next Steps

Getting Started

Lifecycle Events

Performance Optimization

Request Assistant Support

AI Assistant Compatibility

Compatibility Overview

✅ Fully Compatible Assistants

Claude Code Setup

Installation

Configuration

Performance

Troubleshooting

Cursor Setup

Installation

Configuration

Cursor-Specific Features

Performance

Troubleshooting

Windsurf Setup

Installation

Configuration

Windsurf-Specific Features

Performance

Cline (VS Code Extension) Setup

Installation

Limitations

Feature Comparison

Switching Between Assistants

Best Practices

Troubleshooting

General Issues

Next Steps