Hook Performance & Optimization

Every millisecond matters in developer experience. ULPI Hooks are designed for minimal latency impact. This guide explains hook performance characteristics, optimization strategies, and how to tune hooks for your workflow.

Performance Overview

Total Hook Overhead

Across all 8 hooks:

Average latency per hook: ~140ms
Total MCP calls: 14 (distributed across hooks)
Network requests: 14 (one per MCP call)
Perceived user impact: Minimal to none

Key insight: Most hooks are non-blocking or fire at times when latency doesn’t affect user experience.

Hook-by-Hook Performance

session-start: 150ms average

Latency Breakdown
User Impact
Optimization

Total: ~150ms

Operation	Time	Type
Hook trigger	5ms	Local
Register agent (MCP)	50ms	Network
Fetch inbox (MCP)	40ms	Network
List reservations (MCP)	35ms	Network
Search memories (MCP)	60ms	Network
Render dashboard	10ms	Local
Total	200ms	-

Actual perceived: ~150ms (parallel requests optimized)

When it fires: Session start (once per session)User perception:

Session starts in ~150ms vs ~50ms without hooks
100ms additional delay
Acceptable because happens only once
Dashboard provides valuable context worth the wait

Optimization:

Reduce memory loading: minMemoryImportance=0.7
Disable dashboard: showDashboard=false
Result: ~80ms latency

Default config:

{
  "sessionStart": {
    "showDashboard": true,
    "loadMemories": true,
    "minMemoryImportance": 0.5
  }
}

Fast config (minimal latency):

{
  "sessionStart": {
    "showDashboard": false,     // Save 10ms
    "loadMemories": false,       // Save 60ms
    "minMemoryImportance": 0.9   // Load fewer memories
  }
}

Result: ~50ms latency (67% faster)Tradeoff: Less context visibility at session start

pre-tool-use:edit: 120ms average (Fastest Hook)

Latency Breakdown
User Impact
Caching Strategy
Optimization

Total: ~120ms

Operation	Time	Type
Hook trigger	5ms	Local
Check cache (file reservation)	2ms	Local
List reservations (MCP)	60ms	Network (if cache miss)
Create reservation (MCP)	50ms	Network (if creating)
Decision logic	3ms	Local
Total	120ms	-

With cache hit: ~10ms (94% faster)

Cache behavior:

Reservation status cached for 10 seconds
Subsequent edits to same file use cache
Cache invalidated on reservation changes

Example:

00:00 - Edit auth.ts → Check API (120ms) → Reserved
00:05 - Edit auth.ts → Use cache (10ms) → Allowed
00:08 - Edit auth.ts → Use cache (10ms) → Allowed
00:12 - Edit auth.ts → Cache expired → Check API (120ms)

Result: Most edits complete in ~10ms

Extend cache duration:

{
  "preEdit": {
    "cacheDuration": 30  // 30 seconds (default: 10)
  }
}

Benefit: Fewer API calls for rapid file editsTradeoff: Slightly stale reservation statusRecommendation: Use 10-30s for active development

post-tool-use:edit: 80ms average (Non-Blocking)

Latency Breakdown
User Impact
Optimization

Total: ~80ms (async)

Operation	Time	Type
Hook trigger	5ms	Local
Get action items (MCP)	50ms	Network (async)
Update task status (MCP)	30ms	Network (async)
Log audit event	10ms	Local (async)
Total	95ms	Async

Perceived: 0ms (runs in background)

When it fires: After every file edit completesUser perception:

Zero impact (non-blocking)
Edit completes immediately
Hook runs in background
Obligations displayed asynchronously

Example:

User edits file → Save completes immediately
[2 seconds later]
📋 Pending Obligations notification appears

Disable if not needed:

{
  "postEdit": {
    "showObligations": false,  // Skip obligation check
    "updateTasks": false,       // Skip task updates
    "logAudit": true            // Keep audit logging
  }
}

Result: ~10ms latency (90% faster)Use case: Simple projects without task tracking

pre-compact: 200ms average (Slowest Hook)

Latency Breakdown
User Impact
Optimization

Total: ~200ms

Operation	Time	Type
Hook trigger	5ms	Local
Analyze conversation context	80ms	AI processing
Extract important memories	40ms	AI processing
Store memories bulk (MCP)	70ms	Network
Decision logic	5ms	Local
Total	200ms	-

Why slower: AI-powered context analysis requires processing

Reduce memory extraction:

{
  "preCompact": {
    "minImportance": 0.7,      // Only save high-importance (default: 0.5)
    "maxMemoriesPerSnapshot": 50,  // Limit memories (default: 100)
    "includeCode": false        // Skip code snippets
  }
}

Result: ~130ms latency (35% faster)Tradeoff: Fewer memories saved, potentially missing some contextRecommendation:

Use default (0.5) for complex projects
Use 0.7+ for simple projects or quick scripts

user-prompt-submit: 100ms average

Latency Breakdown
User Impact
Optimization

Total: ~100ms

Operation	Time	Type
Hook trigger	5ms	Local
Fetch inbox (urgent only) (MCP)	50ms	Network
Get action items (MCP)	40ms	Network
Decision logic	5ms	Local
Total	100ms	-

Only check urgent messages:

{
  "userPrompt": {
    "urgentOnly": true,         // Skip non-urgent (default: false)
    "showPendingAcks": false,   // Skip pending acks check
    "requireAck": false          // Don't block on urgent messages
  }
}

Result: ~30ms latency (70% faster)Tradeoff: May miss some coordination infoRecommendation: Use defaults for team coordination, optimize for solo work

stop: 90ms average

Latency Breakdown
User Impact
Optimization

Total: ~90ms

Operation	Time	Type
Hook trigger	5ms	Local
Get action items (blocking only) (MCP)	60ms	Network
Decision logic	25ms	Local
Total	90ms	-

Skip safety checks (not recommended):

{
  "stop": {
    "blockUnsafe": false,       // Allow unsafe stops
    "warnPendingAcks": false     // Skip pending acks check
  }
}

Result: ~10ms latencyTradeoff: Risk of orphaned locks, incomplete transactionsRecommendation: Keep enabled for safety

session-end: 110ms average (Non-Blocking)

Latency Breakdown
User Impact
Optimization

Total: ~110ms (async)

Operation	Time	Type
Hook trigger	5ms	Local
Release reservations (MCP)	60ms	Network (async)
Update agent status (MCP)	35ms	Network (async)
Store snapshot (MCP)	50ms	Network (async)
Total	150ms	Async

Perceived: 0ms (runs as session closes)

Skip snapshot creation:

{
  "sessionEnd": {
    "releaseReservations": true,  // Always keep this
    "updateStatus": true,           // Always keep this
    "createSnapshot": false         // Skip final snapshot
  }
}

Result: ~60ms latencyTradeoff: No final session snapshotRecommendation:

Enable createSnapshot for long-term projects
Disable for one-off scripts

subagent-stop: 95ms average (Non-Blocking)

Latency Breakdown
User Impact
Optimization

Total: ~95ms (async)

Operation	Time	Type
Hook trigger	5ms	Local
Store learnings (MCP)	50ms	Network (async)
Release reservations (MCP)	30ms	Network (async)
Update task (MCP)	20ms	Network (async)
Total	105ms	Async

Perceived: 0ms (runs as subagent stops)

Skip learning consolidation:

{
  "subagentStop": {
    "consolidateLearnings": false,  // Skip storing learnings
    "releaseReservations": true,     // Always keep this
    "reportResults": true            // Always keep this
  }
}

Result: ~45ms latencyTradeoff: Subagent learnings not shared with teamRecommendation: Keep enabled for team environments

Performance Summary Table

Hook	Avg Latency	Blocking?	Frequency	User Impact	Optimization Potential
session-start	150ms	✅ Yes	Low	Low	High (⬇️ 67%)
pre-edit	120ms	✅ Yes	High	None	Medium (⬇️ 94% with cache)
post-edit	80ms	❌ No	High	None	High (⬇️ 90%)
pre-compact	200ms	✅ Yes	Very Low	Very Low	Medium (⬇️ 35%)
user-prompt	100ms	✅ Yes	High	Low	High (⬇️ 70%)
stop	90ms	✅ Yes	Low	None	Low (safety-critical)
session-end	110ms	❌ No	Low	None	Medium (⬇️ 45%)
subagent-stop	95ms	❌ No	Medium	None	Medium (⬇️ 57%)

Key Insights:

Fastest: pre-edit (120ms, but 10ms with cache)
Slowest: pre-compact (200ms, but fires rarely)
Most frequent: pre-edit, user-prompt (every edit/prompt)
Most optimizable: session-start (67%), post-edit (90%), user-prompt (70%)

Optimization Strategies

Strategy 1: Aggressive Caching

Use case: Rapid development with frequent edits

{
  "caching": {
    "enabled": true,
    "reservationCacheTTL": 30,      // 30 seconds (default: 10)
    "memoryCacheTTL": 300,           // 5 minutes (default: 60)
    "agentStatusCacheTTL": 60        // 1 minute (default: 30)
  }
}

Impact:

pre-edit: 120ms → 10ms (92% faster for cached files)
session-start: 150ms → 90ms (40% faster for cached memories)

Tradeoff: Slightly stale data (max 30s old) Recommendation: Use for active development on stable teams

Strategy 2: Minimal Features

Use case: Solo developer, no team coordination needed

{
  "hooks": {
    "sessionStart": {
      "showDashboard": false,
      "loadMemories": false
    },
    "postEdit": {
      "showObligations": false,
      "updateTasks": false
    },
    "userPrompt": {
      "showPendingAcks": false
    },
    "sessionEnd": {
      "createSnapshot": false
    }
  }
}

Impact:

session-start: 150ms → 50ms (67% faster)
post-edit: 80ms → 10ms (87% faster)
user-prompt: 100ms → 30ms (70% faster)
session-end: 110ms → 60ms (45% faster)

Tradeoff: Lose team coordination features, memory, obligations Recommendation: Only for solo projects with no team

Strategy 3: Memory-Focused

Use case: Complex project, context preservation critical

{
  "hooks": {
    "preCompact": {
      "minImportance": 0.4,          // Save more memories
      "includeCode": true,
      "maxMemoriesPerSnapshot": 150
    },
    "sessionStart": {
      "loadMemories": true,
      "minMemoryImportance": 0.4     // Load more memories
    },
    "sessionEnd": {
      "createSnapshot": true         // Always snapshot
    }
  }
}

Impact:

pre-compact: 200ms → 250ms (25% slower, but saves more)
session-start: 150ms → 200ms (33% slower, but loads more)

Tradeoff: Higher latency, but better context preservation Recommendation: Use for long-term projects with complex architecture

Strategy 4: Team Coordination Priority

Use case: Multi-agent team, zero conflicts critical

{
  "hooks": {
    "preEdit": {
      "blockConflicts": true,
      "showGuidance": true,
      "cacheDuration": 5             // Shorter cache for real-time updates
    },
    "userPrompt": {
      "showUrgentMessages": true,
      "requireAck": true
    },
    "sessionStart": {
      "showDashboard": true
    }
  }
}

Impact:

pre-edit: Cache hit rate decreases, but fresher data
user-prompt: Always shows urgent messages
session-start: Full dashboard for team awareness

Tradeoff: Slightly higher latency, but better coordination Recommendation: Use for active team development

Network Optimization

Reduce API Calls

Batch MCP tool calls when possible:

{
  "network": {
    "batchRequests": true,           // Batch multiple MCP calls
    "batchWindow": 50,                // Wait 50ms to batch calls
    "parallelRequests": 3             // Max 3 parallel requests
  }
}

Impact:

session-start: 5 API calls → 2 batched calls (40% fewer requests)

Use Regional API Endpoints

Connect to closest ULPI API region:

{
  "apiUrl": "https://api-us-west.ulpi.io"  // Use regional endpoint
}

Regions:

api-us-west.ulpi.io (Oregon)
api-us-east.ulpi.io (Virginia)
api-eu-west.ulpi.io (Ireland)
api-ap-south.ulpi.io (Singapore)

Impact: 60ms → 30ms (50% faster API calls from regional proximity)

Performance Monitoring

Track Hook Execution

# View hook performance stats
ulpi hooks performance

# Output:

🎯 Hook Performance (Last 24 Hours)

Hook Statistics:
├─ session-start (12 executions)
│  ├─ Avg: 145ms
│  ├─ P50: 140ms
│  ├─ P95: 180ms
│  └─ P99: 220ms
│
├─ pre-edit (1,247 executions)
│  ├─ Avg: 18ms (94% cache hits)
│  ├─ P50: 10ms
│  ├─ P95: 120ms
│  └─ P99: 150ms
│
├─ pre-compact (3 executions)
│  ├─ Avg: 195ms
│  ├─ P50: 190ms
│  ├─ P95: 210ms
│  └─ P99: 220ms
│
└─ user-prompt (452 executions)
   ├─ Avg: 102ms
   ├─ P50: 95ms
   ├─ P95: 130ms
   └─ P99: 160ms

Network Efficiency:
- Total API calls: 2,156
- Cached responses: 1,103 (51%)
- Average latency: 58ms
- P95 latency: 95ms

Recommendations:
✓ Cache hit rate excellent (51%)
⚠️  Consider increasing pre-compact minImportance (3 snapshots in 24h)
✓ pre-edit cache performing well (94% hits)

Enable Performance Logging

{
  "debug": true,
  "performance": {
    "logSlowHooks": true,          // Log hooks > 200ms
    "logAllHooks": false,           // Log every hook execution
    "slowThreshold": 200            // Define "slow" as > 200ms
  }
}

Logs:

[2024-01-15T10:30:45Z] Hook: pre-compact, Latency: 245ms ⚠️  SLOW
[2024-01-15T10:30:45Z] └─ Breakdown: analyze(95ms), extract(55ms), store(85ms), other(10ms)

Troubleshooting Slow Hooks

Diagnosis Steps

Identify Slow Hook

ulpi hooks performance --slow-only

Find which hooks exceed threshold.

Enable Debug Logging

ulpi config set debug=true
ulpi config set performance.logSlowHooks=true

Check Network Latency

ulpi network ping

Output:

Pinging ULPI API (https://api.ulpi.io)...
├─ Latency: 85ms
├─ Region: us-west
├─ Suggested: api-us-east.ulpi.io (45ms) ✓

Switch to faster region if suggested.

Review Hook Configuration

ulpi config list --hook session-start

Check if unnecessary features enabled.

Apply Optimizations

Based on findings, apply relevant optimization strategy.

Best Practices

Profile before optimizing

Recommendation: Run performance analysis before making changes

# Baseline performance
ulpi hooks performance --baseline

# Make configuration changes

# Compare after
ulpi hooks performance --compare-to-baseline

Benefit: Know exactly what improved and by how much

Optimize based on usage patterns

Recommendation: Different optimizations for different workflowsSolo developer: Aggressive caching, minimal features Team coordination: Fresh data, full features Long-term project: Memory-focused, context preservation

Monitor performance over time

Recommendation: Track performance trends weekly

ulpi hooks performance --weekly-report

Watch for:

Increasing latency (API degradation)
Decreasing cache hit rate (changing patterns)
Slow hooks (network issues)

Use appropriate cache TTL

Recommendation: Match cache duration to team size

Solo: 60s (very stable)
2-3 people: 30s (mostly stable)
4-6 people: 15s (moderately dynamic)
7+ people: 10s (very dynamic, default)

Rationale: Larger teams change state more frequently

Success Metrics

Teams optimizing hooks report:

94% Cache Hit Rate

For pre-edit hooks with 30s cache TTLRapid file editing nearly instant

Average 85ms Latency

Across all hooks (vs 140ms default)40% faster with optimization

Sub-100ms P95 Latency

95% of hooks complete in under 100msConsistently fast experience

Zero User Complaints

“We never notice the hooks are there”Imperceptible in daily workflows

Next Steps

Getting Started

Install hooks and see performance firsthand

Lifecycle Events

Understand when each hook fires

Configuration Guide

Detailed configuration reference for all hooks

Troubleshooting

Solutions to common performance issues

​Hook Performance & Optimization

​Performance Overview

​Total Hook Overhead

​Hook-by-Hook Performance

​session-start: 150ms average

​pre-tool-use:edit: 120ms average (Fastest Hook)

​post-tool-use:edit: 80ms average (Non-Blocking)

​pre-compact: 200ms average (Slowest Hook)

​user-prompt-submit: 100ms average

​stop: 90ms average

​session-end: 110ms average (Non-Blocking)

​subagent-stop: 95ms average (Non-Blocking)

​Performance Summary Table

​Optimization Strategies

​Strategy 1: Aggressive Caching

​Strategy 2: Minimal Features

​Strategy 3: Memory-Focused

​Strategy 4: Team Coordination Priority

​Network Optimization

​Reduce API Calls

​Use Regional API Endpoints

​Performance Monitoring

​Track Hook Execution

​Enable Performance Logging

​Troubleshooting Slow Hooks

​Diagnosis Steps

​Best Practices

​Success Metrics

94% Cache Hit Rate

Average 85ms Latency

Sub-100ms P95 Latency

Zero User Complaints

​Next Steps

Getting Started

Lifecycle Events

Configuration Guide

Troubleshooting

Hook Performance & Optimization

Performance Overview

Total Hook Overhead

Hook-by-Hook Performance

session-start: 150ms average

pre-tool-use:edit: 120ms average (Fastest Hook)

post-tool-use:edit: 80ms average (Non-Blocking)

pre-compact: 200ms average (Slowest Hook)

user-prompt-submit: 100ms average

stop: 90ms average

session-end: 110ms average (Non-Blocking)

subagent-stop: 95ms average (Non-Blocking)

Performance Summary Table

Optimization Strategies

Strategy 1: Aggressive Caching

Strategy 2: Minimal Features

Strategy 3: Memory-Focused

Strategy 4: Team Coordination Priority

Network Optimization

Reduce API Calls

Use Regional API Endpoints

Performance Monitoring

Track Hook Execution

Enable Performance Logging

Troubleshooting Slow Hooks

Diagnosis Steps

Best Practices

Success Metrics

Next Steps