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:

ULPI Account

API Token

Generate an API token from your API Keys page

Coordination Subscription

Hooks require an active Coordination subscription (Starter $29/mo or higher)

Compatible IDE

Claude Code, Cursor, or Windsurf installed (full support for all 8 hooks)

Bundle Discount: Coordination + Memory subscriptions include Hooks FREE. See pricing for details.

Installation

Step 1: Install the ULPI Package

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

# Install globally for system-wide access
npm install -g ulpi

# Verify installation
ulpi --version

Why global? Global installation makes the ulpi command available everywhere, simplifying setup across multiple projects.

Step 2: Run the Guided Setup Wizard

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

ulpi setup

Enter API Token

When prompted, paste your ULPI API token:

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

Get your API token from app.ulpi.io/api-keys

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.

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)

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.

Manual Setup Not Required: The wizard handles all configuration automatically. You don’t need to edit config files manually unless customizing behavior.

Step 3: Restart Your IDE

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

Claude Code
Cursor
Windsurf
Cline

# Close all Claude Code windows
# Relaunch Claude Code

# Or via CLI:
claude-code --restart

Verify Hooks Are Working

After restarting your IDE, verify hooks are active:

1. Check Hook Status

Run the status command to see active hooks:

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:

╔══════════════════════════════════════════════════════════╗
║  🤖 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                 ║
╚══════════════════════════════════════════════════════════╝

If you see this dashboard: Session-start hook is working! ✅

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

Try editing a file that another agent has reserved:

Identify Reserved File

From the coordination dashboard, note a file reserved by another agent (e.g., auth.ts reserved by Alice)

Attempt to Edit

In your IDE, try to modify that file. The pre-edit hook should block you:

⛔ 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]

Verify Blocking

The edit should be prevented, and you should see the blocking message.

If editing was blocked: Pre-edit hook is working! ✅

4. Test File Reservation (Auto-Reserve)

Edit a file that’s NOT reserved by anyone:

Edit Unreserved File

Open and modify any file not shown in the active reservations list

Check Reservation

After saving, run:

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)

Verify Auto-Reservation

If your file appears in the list: Auto-reservation is working! ✅

5. Test User-Prompt Hook (Message Alerts)

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

Send Urgent Message

From another IDE or via CLI:

ulpi coordination send-message \
  --to "Claude-Code-YourName" \
  --subject "Security issue in auth.ts" \
  --priority urgent \
  --body "Found SQL injection vulnerability in login function"

Submit Prompt

In your IDE, type any message to your AI assistant and press Enter

Check for Alert

Before the AI responds, you should see an urgent message alert:

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

Verify Alert Display

If you see the alert: User-prompt hook is working! ✅

Hook Configuration

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

~/.ulpi/config.json

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

Disable specific hooks

Set "enabled": false for any hook you don’t want:

"preCompact": {
  "enabled": false  // Disable memory snapshots
}

Change default reservation mode

Switch between shared (multiple readers) and exclusive (one writer):

"preEdit": {
  "defaultMode": "exclusive"  // Lock files exclusively
}

Enable debug logging

See detailed hook execution logs:

"debug": true

Logs appear in your IDE’s terminal/console.

Adjust memory snapshot threshold

Control which memories are saved during compaction:

"preCompact": {
  "minImportance": 0.7  // Only save high-importance memories
}

Restart Required: After changing config, restart your IDE for changes to take effect.

Troubleshooting

Hooks not activating after restart

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

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

”Token invalid” error during setup

Symptoms: Setup wizard rejects your API token Solutions:

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

Pre-edit hook not blocking conflicts

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

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

Session-start hook too slow

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

Disable dashboard display: sessionStart.showDashboard = false
Don’t load all memories: sessionStart.loadMemories = false
Check network latency to ULPI API
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:

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

Advanced: Manual Hook Installation

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

Create Config Directory

mkdir -p ~/.ulpi

Create Config File

cat > ~/.ulpi/config.json << EOF
{
  "apiToken": "your-token-here",
  "apiUrl": "https://api.ulpi.io",
  "hooks": {
    "enabled": true
  }
}
EOF

Install IDE-Specific Hooks

Claude Code
Cursor
VS Code (Cline)

# Create hooks directory
mkdir -p ~/.claude-code/hooks

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

Verify Installation

ulpi hooks status

Next Steps

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

Lifecycle Events Deep Dive

Learn exactly when each hook fires and what MCP tools it uses

File Conflict Prevention

Master the pre-edit hook and achieve zero merge conflicts

Memory Integration

Preserve context automatically with pre-compact memory snapshots

Real-World Use Cases

See how teams use hooks to coordinate 3, 5, or 10+ agents

Getting Started

Documentation

Skills

Coordination

Memory

Hooks

Tasks

Help & Security

Getting Started with Hooks

Getting Started with ULPI Hooks

Prerequisites

ULPI Account

API Token

Coordination Subscription

Compatible IDE

Installation

Step 1: Install the ULPI Package

Step 2: Run the Guided Setup Wizard

Step 3: Restart Your IDE

Verify Hooks Are Working

1. Check Hook Status

2. Test Session Start Hook

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

4. Test File Reservation (Auto-Reserve)

5. Test User-Prompt Hook (Message Alerts)

Hook Configuration

Common Customizations

Troubleshooting

Hooks not activating after restart

”Token invalid” error during setup

Pre-edit hook not blocking conflicts

Session-start hook too slow

Hooks work in one IDE but not another

Advanced: Manual Hook Installation

Next Steps

Lifecycle Events Deep Dive

File Conflict Prevention

Memory Integration

Real-World Use Cases

Getting Started

Documentation

Skills

Coordination

Memory

Hooks

Tasks

Help & Security

​Getting Started with ULPI Hooks

​Prerequisites

ULPI Account

API Token

Coordination Subscription

Compatible IDE

​Installation

​Step 1: Install the ULPI Package

​Step 2: Run the Guided Setup Wizard

​Step 3: Restart Your IDE

​Verify Hooks Are Working

​1. Check Hook Status

​2. Test Session Start Hook

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

​4. Test File Reservation (Auto-Reserve)

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

​Hook Configuration

​Common Customizations

​Troubleshooting

​Hooks not activating after restart

​”Token invalid” error during setup

​Pre-edit hook not blocking conflicts

​Session-start hook too slow

​Hooks work in one IDE but not another

​Advanced: Manual Hook Installation

​Next Steps

Lifecycle Events Deep Dive

File Conflict Prevention

Memory Integration

Real-World Use Cases

Getting Started with ULPI Hooks

Prerequisites

Installation

Step 1: Install the ULPI Package

Step 2: Run the Guided Setup Wizard

Step 3: Restart Your IDE

Verify Hooks Are Working

1. Check Hook Status

2. Test Session Start Hook

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

4. Test File Reservation (Auto-Reserve)

5. Test User-Prompt Hook (Message Alerts)

Hook Configuration

Common Customizations

Troubleshooting

Hooks not activating after restart

”Token invalid” error during setup

Pre-edit hook not blocking conflicts

Session-start hook too slow

Hooks work in one IDE but not another

Advanced: Manual Hook Installation

Next Steps