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

# Performance & Optimization

> Detailed latency analysis, optimization strategies, and performance tuning for ULPI Hooks

# 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

<Tabs>
  <Tab title="Latency Breakdown">
    **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)
  </Tab>

  <Tab title="User Impact">
    **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
  </Tab>

  <Tab title="Optimization">
    **Default config:**

    ```json theme={null}
    {
      "sessionStart": {
        "showDashboard": true,
        "loadMemories": true,
        "minMemoryImportance": 0.5
      }
    }
    ```

    **Fast config (minimal latency):**

    ```json theme={null}
    {
      "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
  </Tab>
</Tabs>

***

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

<Tabs>
  <Tab title="Latency Breakdown">
    **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)
  </Tab>

  <Tab title="User Impact">
    **When it fires:** Before every file edit

    **User perception:**

    * **Imperceptible in normal workflows**
    * Edit tool appears instantly
    * Reservation check happens in background
    * Only noticeable if edit is blocked

    **Frequency:** High (every edit)

    * But 80% of calls are cache hits (\~10ms)
    * Only 20% make network requests (\~120ms)
  </Tab>

  <Tab title="Caching Strategy">
    **Cache behavior:**

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

    **Example:**

    ```plaintext theme={null}
    09:00:00 - Edit auth.ts → Check API (120ms) → Reserved
    09:00:05 - Edit auth.ts → Use cache (10ms) → Allowed
    09:00:08 - Edit auth.ts → Use cache (10ms) → Allowed
    09:00:12 - Edit auth.ts → Cache expired → Check API (120ms)
    ```

    **Result:** Most edits complete in \~10ms
  </Tab>

  <Tab title="Optimization">
    **Extend cache duration:**

    ```json theme={null}
    {
      "preEdit": {
        "cacheDuration": 30  // 30 seconds (default: 10)
      }
    }
    ```

    **Benefit:** Fewer API calls for rapid file edits

    **Tradeoff:** Slightly stale reservation status

    **Recommendation:** Use 10-30s for active development
  </Tab>
</Tabs>

***

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

<Tabs>
  <Tab title="Latency Breakdown">
    **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)
  </Tab>

  <Tab title="User Impact">
    **When it fires:** After every file edit completes

    **User perception:**

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

    **Example:**

    ```plaintext theme={null}
    User edits file → Save completes immediately
    [2 seconds later]
    📋 Pending Obligations notification appears
    ```
  </Tab>

  <Tab title="Optimization">
    **Disable if not needed:**

    ```json theme={null}
    {
      "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
  </Tab>
</Tabs>

***

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

<Tabs>
  <Tab title="Latency Breakdown">
    **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
  </Tab>

  <Tab title="User Impact">
    **When it fires:** Before context compaction (\~every 2-3 hours)

    **User perception:**

    * Compaction delayed by \~200ms
    * **Acceptable because:**
      * Fires infrequently (every 2-3 hours)
      * Saves 15-30 min of re-explanation time
      * ROI: 200ms cost → 15 min savings = **4500x return**

    **Frequency:** Low (2-3 times per day in long sessions)
  </Tab>

  <Tab title="Optimization">
    **Reduce memory extraction:**

    ```json theme={null}
    {
      "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 context

    **Recommendation:**

    * Use default (0.5) for complex projects
    * Use 0.7+ for simple projects or quick scripts
  </Tab>
</Tabs>

***

### user-prompt-submit: 100ms average

<Tabs>
  <Tab title="Latency Breakdown">
    **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** | -       |
  </Tab>

  <Tab title="User Impact">
    **When it fires:** Before every AI response

    **User perception:**

    * AI response delayed by \~100ms
    * **Usually imperceptible:**
      * User expects 1-2s for AI to respond
      * 100ms is 5-10% of total response time
      * Only noticeable if urgent message blocks response

    **Frequency:** High (every user prompt)
  </Tab>

  <Tab title="Optimization">
    **Only check urgent messages:**

    ```json theme={null}
    {
      "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 info

    **Recommendation:** Use defaults for team coordination, optimize for solo work
  </Tab>
</Tabs>

***

### stop: 90ms average

<Tabs>
  <Tab title="Latency Breakdown">
    **Total: \~90ms**

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

  <Tab title="User Impact">
    **When it fires:** User clicks stop/cancel

    **User perception:**

    * Stop action delayed by \~90ms
    * **Acceptable because:**
      * Prevents unsafe shutdowns
      * Only fires when user manually stops
      * 90ms unnoticeable in stop action

    **Frequency:** Low (only when user manually stops execution)
  </Tab>

  <Tab title="Optimization">
    **Skip safety checks (not recommended):**

    ```json theme={null}
    {
      "stop": {
        "blockUnsafe": false,       // Allow unsafe stops
        "warnPendingAcks": false     // Skip pending acks check
      }
    }
    ```

    **Result:** \~10ms latency

    **Tradeoff:** Risk of orphaned locks, incomplete transactions

    **Recommendation:** Keep enabled for safety
  </Tab>
</Tabs>

***

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

<Tabs>
  <Tab title="Latency Breakdown">
    **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)
  </Tab>

  <Tab title="User Impact">
    **When it fires:** Session ends (window closes, chat ends, etc.)

    **User perception:**

    * **Zero impact** (runs in background as session closes)
    * User doesn't wait for hook to complete
    * Cleanup happens asynchronously

    **Frequency:** Low (once per session)
  </Tab>

  <Tab title="Optimization">
    **Skip snapshot creation:**

    ```json theme={null}
    {
      "sessionEnd": {
        "releaseReservations": true,  // Always keep this
        "updateStatus": true,           // Always keep this
        "createSnapshot": false         // Skip final snapshot
      }
    }
    ```

    **Result:** \~60ms latency

    **Tradeoff:** No final session snapshot

    **Recommendation:**

    * Enable `createSnapshot` for long-term projects
    * Disable for one-off scripts
  </Tab>
</Tabs>

***

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

<Tabs>
  <Tab title="Latency Breakdown">
    **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)
  </Tab>

  <Tab title="User Impact">
    **When it fires:** Subagent completes task

    **User perception:**

    * **Zero impact** (subagent cleanup is background)
    * Parent agent notified when complete
    * No user-facing delay

    **Frequency:** Medium (when using subagents for parallel work)
  </Tab>

  <Tab title="Optimization">
    **Skip learning consolidation:**

    ```json theme={null}
    {
      "subagentStop": {
        "consolidateLearnings": false,  // Skip storing learnings
        "releaseReservations": true,     // Always keep this
        "reportResults": true            // Always keep this
      }
    }
    ```

    **Result:** \~45ms latency

    **Tradeoff:** Subagent learnings not shared with team

    **Recommendation:** Keep enabled for team environments
  </Tab>
</Tabs>

***

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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

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

# Output:
```

```plaintext theme={null}
🎯 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

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

**Logs:**

```plaintext theme={null}
[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

<Steps>
  <Step title="Identify Slow Hook">
    ```bash theme={null}
    ulpi hooks performance --slow-only
    ```

    Find which hooks exceed threshold.
  </Step>

  <Step title="Enable Debug Logging">
    ```bash theme={null}
    ulpi config set debug=true
    ulpi config set performance.logSlowHooks=true
    ```
  </Step>

  <Step title="Check Network Latency">
    ```bash theme={null}
    ulpi network ping
    ```

    **Output:**

    ```plaintext theme={null}
    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.
  </Step>

  <Step title="Review Hook Configuration">
    ```bash theme={null}
    ulpi config list --hook session-start
    ```

    Check if unnecessary features enabled.
  </Step>

  <Step title="Apply Optimizations">
    Based on findings, apply relevant optimization strategy.
  </Step>
</Steps>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Profile before optimizing" icon="chart-line">
    **Recommendation:** Run performance analysis before making changes

    ```bash theme={null}
    # 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
  </Accordion>

  <Accordion title="Optimize based on usage patterns" icon="puzzle-piece">
    **Recommendation:** Different optimizations for different workflows

    **Solo developer:** Aggressive caching, minimal features
    **Team coordination:** Fresh data, full features
    **Long-term project:** Memory-focused, context preservation
  </Accordion>

  <Accordion title="Monitor performance over time" icon="calendar">
    **Recommendation:** Track performance trends weekly

    ```bash theme={null}
    ulpi hooks performance --weekly-report
    ```

    **Watch for:**

    * Increasing latency (API degradation)
    * Decreasing cache hit rate (changing patterns)
    * Slow hooks (network issues)
  </Accordion>

  <Accordion title="Use appropriate cache TTL" icon="clock">
    **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
  </Accordion>
</AccordionGroup>

***

## Success Metrics

Teams optimizing hooks report:

<CardGroup cols={2}>
  <Card title="94% Cache Hit Rate" icon="gauge-high" color="#10b981">
    For pre-edit hooks with 30s cache TTL

    Rapid file editing nearly instant
  </Card>

  <Card title="Average 85ms Latency" icon="bolt" color="#3b82f6">
    Across all hooks (vs 140ms default)

    40% faster with optimization
  </Card>

  <Card title="Sub-100ms P95 Latency" icon="chart-line" color="#8b5cf6">
    95% of hooks complete in under 100ms

    Consistently fast experience
  </Card>

  <Card title="Zero User Complaints" icon="smile" color="#f59e0b">
    "We never notice the hooks are there"

    Imperceptible in daily workflows
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/hooks/getting-started">
    Install hooks and see performance firsthand
  </Card>

  <Card title="Lifecycle Events" icon="diagram-project" href="/hooks/lifecycle-events">
    Understand when each hook fires
  </Card>

  <Card title="Configuration Guide" icon="sliders" href="/hooks/configuration">
    Detailed configuration reference for all hooks
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/hooks/troubleshooting">
    Solutions to common performance issues
  </Card>
</CardGroup>