> ## 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. # Real-World Use Cases > See how teams use ULPI Hooks to coordinate agents, prevent conflicts, and preserve context # Real-World Use Cases for ULPI Hooks **Theory is great. Real-world results are better.** This guide shows how actual development teams use ULPI Hooks to solve coordination problems, eliminate merge conflicts, and preserve critical context. Each use case includes: the problem, the solution using hooks, and measurable results. *** ## Use Case 1: Multi-Agent Development Team ### The Problem **Team Setup:** * 3 developers (Alice, Bob, Charlie) * All using AI coding assistants (Claude Code, Cursor, Windsurf) * Working on same repository simultaneously * Microservices architecture with shared code **Pain Points Before Hooks:** * 15-20 merge conflicts per week * 3-4 hours weekly spent resolving conflicts * Duplicate work (two people implementing same feature) * Communication overhead (constant "are you editing X?" messages) * Frustration and context switching *** ### The Solution with Hooks #### **session-start Hook: Team Awareness** Every morning when team members start their AI sessions: ```plaintext theme={null} ╔══════════════════════════════════════════════════════╗ ║ 🤖 ULPI Coordination Dashboard ║ ╠══════════════════════════════════════════════════════╣ ║ 📬 Messages: 2 unread (1 from Alice) ║ ║ ║ ║ 👥 Online Agents: ║ ║ ├─ Alice (Cursor) - working on auth module ║ ║ ├─ Bob (Claude Code) - refactoring API endpoints ║ ║ └─ You (Windsurf) - just joined ║ ║ ║ ║ 🔒 Active Reservations: ║ ║ ├─ src/auth/login.ts (Alice, exclusive, 1h left) ║ ║ ├─ src/api/routes.ts (Bob, shared, 2h left) ║ ║ └─ database/migrations/007.sql (Alice, exclusive) ║ ╚══════════════════════════════════════════════════════╝ ``` **Benefit:** Instant visibility into who's working on what *** #### **pre-edit Hook: Automatic Conflict Prevention** **Scenario:** Charlie tries to edit `src/auth/login.ts` while Alice is working on it **Without hooks:** * Charlie edits the file * Alice also edits the file * Both commit locally * Merge conflict when syncing * 15 minutes lost to resolution **With hooks:** ```plaintext theme={null} ⛔ Edit Blocked - File Reserved File: src/auth/login.ts Reserved by: Alice (Cursor) Mode: Exclusive Expires: 1 hour 15 minutes Alice is implementing OAuth login. Estimated completion: 1.5 hours Coordination Options: 1. [Message Alice] - "When will you be done?" 2. [Check her progress] - View Alice's commits 3. [Work on related file] - auth/middleware.ts available 4. [Set reminder] - Notify when file is available [Choose Option] ``` Charlie chooses option 1 (Message Alice): ```plaintext theme={null} 📨 Message to Alice Charlie: "Hey Alice, I need to add rate limiting to the login function. When will you be done with login.ts?" Alice: "I'm adding OAuth, should be done in 30 min. But rate limiting can go in middleware/rateLimiter.ts and I'll call it from login. Want to pair on the integration?" Charlie: "Perfect! I'll build the middleware now." ``` **Result:** * Zero conflict * Better architecture (middleware separation) * Collaboration opportunity * Both make progress *** ### Results After 3 Months **Before:** 15-20/week **After:** 0-1/week (99% reduction) The 1 remaining conflict was a force override for emergency hotfix **Before:** 3-4 hours/week resolving conflicts **After:** 0 hours (15 minutes monthly) **Annual savings:** 150 hours per developer **Before:** Constant "are you editing X?" Slack messages **After:** Coordination through ULPI messaging **Benefit:** Async, contextual, automated **Before:** Frustration with conflicts **After:** "We never think about conflicts anymore" **Quote:** "Hooks just work. We forget they're there." — Alice *** ## Use Case 2: Parallel Task Execution with Subagents ### The Problem **Scenario:** * Main agent orchestrating a large refactor * Needs to update 20 files across 5 modules * Sequential execution would take 6 hours * Want to parallelize using subagents **Challenges:** * Subagents might edit same files (conflicts) * Main agent loses subagent learnings after they stop * No visibility into subagent progress * File locks orphaned if subagent crashes *** ### The Solution with Hooks #### **Task Orchestration with Hooks** **Main agent spawns 5 subagents:** ```typescript theme={null} // Main agent distributes work const tasks = [ { subagent: 1, files: ['auth/login.ts', 'auth/logout.ts'] }, { subagent: 2, files: ['api/users.ts', 'api/posts.ts'] }, { subagent: 3, files: ['database/schema.ts', 'database/migrations/008.sql'] }, { subagent: 4, files: ['tests/auth.test.ts', 'tests/api.test.ts'] }, { subagent: 5, files: ['docs/api.md', 'docs/auth.md'] }, ]; // Each subagent claims its files via pre-edit hooks ``` *** #### **pre-edit Hook: File Claiming** **Subagent 1** starts editing `auth/login.ts`: ```plaintext theme={null} 🎣 Pre-Edit Hook (Subagent-1) File: auth/login.ts Action: Reserve (exclusive mode for subagent) ✓ File reserved successfully Reservation ID: res_sub1_abc123 ``` **Subagent 2** starts editing `api/users.ts`: ```plaintext theme={null} ✓ File reserved (no conflict with Subagent 1) ``` **No subagent can edit another's claimed files.** *** #### **subagent-stop Hook: Learning Consolidation** **Subagent 1 completes its task:** ```plaintext theme={null} 🎣 Subagent-Stop Hook Fired Subagent: Subagent-1 Task: Refactor auth module Duration: 18 minutes Files edited: 2 (login.ts, logout.ts) Consolidating learnings to shared memory: ✓ Stored: OAuth implementation pattern (salience: 0.85) ✓ Stored: Error handling approach (salience: 0.80) ✓ Stored: JWT token validation logic (salience: 0.75) Releasing file reservations: ✓ Released: auth/login.ts ✓ Released: auth/logout.ts Reporting to Main Agent: ✓ Task completed ✓ 2 files refactored ✓ 12 tests passing ``` **Main agent receives:** ```plaintext theme={null} 📊 Subagent-1 Report Status: Completed Files: 2/2 ✓ Tests: 12/12 passing ✓ Learnings: 3 patterns stored to memory Available for Main Agent to review and other subagents to use. ``` *** #### **session-start Hook: Cross-Subagent Learning** **Subagent 4** (working on tests) starts and loads memories from Subagent 1: ```plaintext theme={null} 🚀 Subagent-4 Session Start 🧠 Loading relevant memories from other subagents: ✓ Loaded: OAuth implementation pattern (from Subagent-1) ✓ Loaded: Error handling approach (from Subagent-1) Subagent-4 can now write tests that match the patterns used in the auth refactor, even though it didn't do that work. ``` *** ### Results **Sequential execution (without subagents):** * 20 files × 18 minutes/file = 6 hours **Parallel with subagents (without hooks):** * 5 subagents × 1.2 hours = 1.2 hours + 45 min conflict resolution = **2 hours** **Parallel with hooks:** * 5 subagents × 1.2 hours = **1.2 hours** (zero conflicts) **Speedup: 5x faster than sequential, 40% faster than unhook parallel** **Without hooks:** * Subagents duplicate patterns (no shared learnings) * Tests don't match implementation conventions * Inconsistent error handling across modules **With hooks:** * Subagent learnings shared via memory * Consistent patterns across all refactored files * Tests match implementation from the start **Without hooks:** * 3 file conflicts required manual resolution * 1 subagent crash left orphaned file locks * Main agent didn't know when subagents completed **With hooks:** * Zero file conflicts (pre-edit hooks prevented) * session-end hooks auto-released all locks * Main agent notified instantly on completion *** ## Use Case 3: Context Preservation for Long Projects ### The Problem **Scenario:** * 6-month project building a new platform * Multiple AI sessions over months * Critical architecture decisions made early on * New features added monthly **Challenges:** * Context compacted every few hours * Architecture decisions forgotten * New AI sessions start from scratch * Re-explaining project context daily **Time waste:** * 15 minutes/session re-explaining context * 3 sessions/day = 45 minutes daily * 225 minutes/week = **3.75 hours weekly** *** ### The Solution with Hooks #### **Month 1: Architecture Planning** **Conversation with Claude:** ``` User: "We're building a social platform. PostgreSQL or MongoDB?" Claude: "For your use case, PostgreSQL because: 1. Strong relationships (users, posts, comments) 2. ACID compliance for financial data (premium subscriptions) 3. Full-text search built-in 4. Your team knows SQL" User: "Agreed. This is critical for the whole project architecture." ``` **Pre-compact hook fires (context approaching limit):** ```plaintext theme={null} 💾 Saving Architecture Decision Content: "PostgreSQL chosen over MongoDB for social platform. Rationale: Relational data model, ACID compliance for payments, full-text search, team expertise." Type: architecture_decision Importance: 0.98 Tags: ["database", "architecture", "postgresql"] ✓ Stored to memory ``` *** #### **Month 2: New Feature (Payments)** **New AI session starts:** ```plaintext theme={null} 🧠 Loading Relevant Memories Project: social-platform Loading high-importance memories... ✓ Loaded 23 architecture decisions ✓ Loaded 15 code conventions ✓ Loaded 8 key insights Including: - PostgreSQL database choice and rationale - Microservices architecture decisions - API design patterns - ... ``` **Conversation:** ``` User: "We're adding payments. What database should we use?" Claude: "Based on our architecture decision from Month 1, we're using PostgreSQL for the whole platform. For payments specifically, PostgreSQL is ideal because we need ACID compliance for transactions. I recommend: - payments table in main PostgreSQL database - Use transactions for payment operations - Leverage PostgreSQL's ACID guarantees" User: "Perfect!" [Claude remembered without re-explanation] ``` **Time saved: 15 minutes** (didn't re-explain DB choice) *** #### **Month 4: New Team Member** **New developer (David) joins:** ```bash theme={null} # David searches project memories ulpi memory search --project social-platform --limit 50 # Results: ``` ```plaintext theme={null} 📚 Project Memory Archive Architecture Decisions (12): 1. PostgreSQL database (importance: 0.98, month 1) Rationale: Relational model, ACID, full-text search 2. Microservices architecture (importance: 0.95, month 1) Rationale: Team size, scalability, deployment flexibility 3. REST over GraphQL (importance: 0.90, month 2) Rationale: Simpler, team familiarity, caching ... Code Conventions (15): 1. Error handling pattern (importance: 0.85) 2. API response format (importance: 0.80) 3. Testing strategy (importance: 0.85) ... Key Insights (24): 1. N+1 query optimization pattern (importance: 0.75) 2. Caching strategy for user feeds (importance: 0.80) ... ``` **David's onboarding:** * **Before hooks:** 2 weeks to understand architecture * **With hooks:** 3 days (reads memory archive, asks clarifying questions) *** ### Results After 6 Months **Before:** 3.75 hours/week **After:** 0 hours **Total saved:** 90 hours over 6 months **Before:** Decisions forgotten, inconsistent approaches **After:** 100% consistency with original architecture New features align with month 1 decisions **Before:** 2 weeks for new developers **After:** 3 days Memory archive serves as living documentation **Before:** 40% of decisions remembered after compaction **After:** 100% of important decisions preserved Nothing lost to context compaction *** ## Use Case 4: Emergency Code Freeze ### The Problem **Scenario:** * Friday 4 PM: Security vulnerability discovered in production * Need immediate code freeze (no deploys until patched) * 5 developers actively working with AI assistants * Need to alert all agents instantly **Challenges:** * Agents don't know about security issue * Might deploy vulnerable code * Need instant coordination across all agents *** ### The Solution with Hooks #### **1. Send Urgent Message to All Agents** ```bash theme={null} # Security team sends urgent broadcast ulpi coordination broadcast \ --priority urgent \ --subject "SECURITY: Code freeze - SQL injection vulnerability" \ --body "Critical SQL injection found in user auth. CODE FREEZE until patched. Do not deploy. Do not modify auth module." \ --all-agents ``` *** #### **2. user-prompt-submit Hook Alerts** **Every agent sees alert before next response:** **Alice (Cursor):** ```plaintext theme={null} 🚨 URGENT COORDINATION MESSAGE From: Security Team Priority: CRITICAL Subject: Code freeze - SQL injection vulnerability Critical SQL injection found in user auth. ⛔ CODE FREEZE: - Do not deploy any code - Do not modify auth module - Wait for security patch [Acknowledge] [View Details] ``` Alice clicks \[Acknowledge] → Can continue non-auth work *** **Bob (Claude Code):** Bob is about to modify `auth/login.ts` when: ```plaintext theme={null} 🚨 URGENT MESSAGE + PRE-EDIT HOOK BLOCK ⛔ Edit Blocked File: auth/login.ts Reason: Emergency code freeze (security issue) You have unacknowledged urgent message about this file. You must acknowledge before editing auth-related files. [View Urgent Message] [Acknowledge] ``` Bob views message → Understands → Works on different module *** #### **3. Pre-Edit Hook: Enforce Freeze** **Configuration update (instant):** ```bash theme={null} # Security team adds auth module to blocked files ulpi coordination block-files \ --pattern "src/auth/**" \ --reason "Emergency security patch in progress" \ --duration 2h ``` **Now pre-edit hooks block ALL auth file edits:** ```plaintext theme={null} ⛔ Edit Blocked - Emergency Freeze File: src/auth/middleware.ts Reason: Emergency security patch in progress Duration: 1 hour 45 minutes remaining Security team is patching SQL injection vulnerability. Auth module is frozen until patch is deployed. [Contact Security Team] [View Details] [OK] ``` *** ### Results **Traditional:** Email/Slack (5-30 min to reach everyone) **With hooks:** Instant (next user prompt) **All 5 agents alerted within 2 minutes** **Without hooks:** 2 agents deployed vulnerable code **With hooks:** 0 deploys during freeze **Security maintained** **Traditional:** 30 min of Slack messages to coordinate **With hooks:** 2 minutes (auto-alerts + acknowledgments) **93% faster coordination** **Total time:** 45 minutes (patch + deploy) **Zero conflicting changes during freeze** Smooth, coordinated response *** ## Use Case 5: Multi-Codebase Development ### The Problem **Scenario:** * Microservices architecture (8 services) * Developer works across multiple repos daily * Each service has different conventions * Each repo has different AI context **Challenges:** * Context doesn't transfer between repos * Conventions forgotten when switching repos * Re-explain architecture for each service *** ### The Solution with Hooks #### **session-start Hook: Load Repo-Specific Context** **Switch to auth-service repo:** ```plaintext theme={null} 🚀 Session Start: auth-service 🧠 Loading auth-service memories: ✓ Architecture: OAuth 2.0 with JWT tokens ✓ Convention: Winston logger for all errors ✓ Convention: Jest with 80% coverage minimum ✓ Active tasks: Rate limiting implementation (60% done) Claude now has auth-service context. ``` **15 minutes later, switch to payment-service repo:** ```plaintext theme={null} 🚀 Session Start: payment-service 🧠 Loading payment-service memories: ✓ Architecture: Stripe integration with webhook handling ✓ Convention: Pino logger (different from auth-service!) ✓ Convention: Supertest for API tests ✓ Active tasks: Subscription management (planning phase) Claude now has payment-service context. ``` *** #### **Context Isolation** **Key benefit:** Each repo's context is separate ``` User (in payment-service): "Add error logging" Claude: "I'll use Pino logger as per payment-service conventions: logger.error({ err, userId }, 'Payment processing failed'); " ``` **Claude used Pino (payment-service convention), not Winston (auth-service convention)** *** ### Results **Before:** 10 min/switch (re-explain conventions) **After:** 0 min (auto-loaded memories) **5 switches/day × 10 min = 50 min saved daily** **Before:** Mixed conventions (used wrong logger in 3 repos) **After:** 100% consistent with each repo's standards No cross-contamination **Before:** Forgot which tasks active in which repo **After:** Active tasks loaded per repo Resume exactly where you left off **Before:** Mental effort to remember each repo's patterns **After:** Zero effort (hooks handle it) Developer focus on actual code, not conventions *** ## Use Case 6: Compliance & Audit Trail ### The Problem **Scenario:** * Financial services company (regulated industry) * Must maintain audit trail of all code changes * Need to prove who changed what and why * AI-assisted development complicates attribution **Compliance requirements:** * Track every file modification * Identify human developer and AI assistant used * Record rationale for changes * Demonstrate review process *** ### The Solution with Hooks #### **post-edit Hook: Automatic Audit Logging** **Every file edit automatically logged:** ```plaintext theme={null} 📝 Audit Log Entry Created Timestamp: 2024-01-15T14:32:18Z Developer: alice@company.com AI Assistant: Claude Code (Claude Sonnet 4.5) Agent ID: claude-code-alice File: src/payments/processor.ts Action: Edit Lines changed: 45-67 (23 lines) Diff size: +85, -42 Change summary: "Added fraud detection validation before payment processing" Compliance metadata: - Reservation ID: res_abc123 - Code review: Required (2 approvals pending) - Security scan: Passed - Test coverage: 92% (above 80% minimum) ✓ Logged to compliance database ``` *** #### **session-start & session-end Hooks: Session Tracking** **Session start:** ```plaintext theme={null} 📊 Session Started Developer: alice@company.com Agent: Claude Code Project: payment-platform Timestamp: 2024-01-15T09:00:00Z Compliance requirements active: ✓ SOC 2 Type II ✓ PCI DSS Level 1 ✓ GDPR All actions will be logged for audit. ``` **Session end:** ```plaintext theme={null} 📊 Session Summary Duration: 3 hours 15 minutes Files edited: 8 Total changes: +420, -185 lines Code reviews initiated: 2 Security scans: 8 passed, 0 failed All actions logged to compliance database. Audit trail: audit_log_xyz789 ``` *** ### Results **Before:** Manual logging (inconsistent, often forgotten) **After:** 100% automated, complete audit trail **Passed SOC 2 audit with zero findings** **Before:** Unclear if human or AI made change **After:** Perfect attribution (human + AI assistant tracked) **Regulators satisfied with transparency** **Before:** 30 min/day manual audit logging **After:** 0 min (fully automated) **125 hours saved annually per developer** **Before:** Some changes untracked (security risk) **After:** Every change tracked and logged **Zero unauthorized changes** *** ## Summary: Hooks ROI by Use Case | Use Case | Time Saved | Key Benefit | Difficulty | | -------------------- | ------------- | ----------------------------- | ------------ | | Multi-Agent Team | 3-4 hrs/week | Zero merge conflicts | ⭐ Easy | | Parallel Subagents | 5x speedup | Conflict-free parallelization | ⭐⭐ Moderate | | Context Preservation | 3.75 hrs/week | No re-explanation needed | ⭐ Easy | | Emergency Freeze | 93% faster | Instant team coordination | ⭐ Easy | | Multi-Codebase | 50 min/day | Auto-context switching | ⭐ Easy | | Compliance | 125 hrs/year | Perfect audit trail | ⭐⭐⭐ Advanced | *** ## Next Steps Install hooks in 5 minutes and start coordinating Deep dive into zero-conflict file management Learn how to preserve 100% of critical context Understand hook latency and optimization strategies