Codeman/.claude/optimization-todos.md

Claudeman Code Optimization TODO List

Generated: 2026-01-21 Purpose: Comprehensive optimization roadmap for future sessions

Overview

This document contains prioritized optimization tasks identified through codebase analysis. Each item has specific file:line references and expected impact estimates.

---

HIGH PRIORITY OPTIMIZATIONS

1. String Concatenation in Hot Paths

• Files: src/session.ts:460, 677-686, src/respawn-controller.ts:469, 826, src/inner-loop-tracker.ts:408
• Issue: String += in terminal buffer accumulation creates GC pressure
• Fix: Use array-based accumulation with periodic joins
• Impact: 10-20% faster terminal streaming

2. Regex Pattern lastIndex Reset

• Files: src/inner-loop-tracker.ts:464-479, src/screen-manager.ts:264
• Issue: Global regex without lastIndex reset causes skip-every-other-match bug
• Fix: Always reset pattern.lastIndex = 0 before use
• Impact: Correct pattern matching, eliminate intermittent bugs

3. Unbounded Buffer Growth

• Files: src/respawn-controller.ts:268-269, src/inner-loop-tracker.ts:257-258
• Issue: Buffers lack proper size limits or have loose limits
• Fix: Add hard limits with Ring Buffer pattern
• Impact: Bounded memory, prevent OOM in long sessions

4. Event Listener Management

• Files: src/respawn-controller.ts:446-455, src/session.ts:481-501, src/web/server.ts:987-1084
• Issue: Listeners created repeatedly without cleanup tracking
• Fix: Use debounce/throttle utilities, consolidate timeout management
• Impact: Fewer memory leaks, reduced GC sweeps

5. Task Lookup Optimization

• Files: src/task-tracker.ts:214-220, 231-234
• Issue: O(n) sequential iteration for task lookups
• Fix: Add secondary indices runningTasksByType: Map<string, Set<string>>
• Impact: O(1) lookups, faster with 1000+ tasks

---

MEDIUM PRIORITY OPTIMIZATIONS

6. Pattern Test Result Caching

• Files: src/inner-loop-tracker.ts:529-543
• Issue: Multiple pattern tests on same data without caching
• Fix: Use .exec() once and reuse result
• Impact: 2-3x faster todo detection

7. Dynamic Terminal Batching

• Files: src/web/server.ts:46, 1350-1360
• Issue: 16ms flush interval is too long for interactive sessions
• Fix: Flush immediately if batch > 1KB OR timeout 16ms
• Impact: Snappier UI feel

8. Buffer Pagination

• Files: src/session.ts:314-365, src/web/server.ts:219-224
• Issue: Full buffer sent on every state update
• Fix: Add /api/sessions/:id/history?offset=X&limit=Y
• Impact: 10-100x faster reconnects

9. Remove Unused Regex Patterns

• Files: src/respawn-controller.ts:52-59
• Issue: ANSI_ESCAPE_PATTERN, WHITESPACE_PATTERN marked @deprecated but still compiled
• Fix: Remove unused patterns
• Impact: Cleaner code, slightly faster startup

10. State Serialization

• Files: src/state-store.ts:80, 196, src/web/server.ts:1343
• Issue: Full JSON.stringify on every save
• Fix: Incremental or selective serialization
• Impact: 5-10x faster state saves

---

LOW PRIORITY OPTIMIZATIONS

11. Error Handling Consistency

• Files: src/screen-manager.ts:101-104, src/session.ts:726-729, src/web/server.ts:838-845
• Issue: Mix of try-catch and error codes
• Fix: Create ErrorRegistry, standardize responses
• Impact: Better debugging

12. TypeScript Strict Typing

• Files: src/task-tracker.ts:179, src/web/server.ts:138, 174
• Issue: Some implicit any types
• Fix: Strong typing for all messages and payloads
• Impact: Better IDE support, fewer runtime errors

13. Dead Code Removal

• Files: src/task.ts, src/task-queue.ts, src/ralph-loop.ts
• Issue: Potentially unused files
• Fix: Verify imports, remove unused
• Impact: Cleaner codebase

14. Console Logging

• Files: Throughout src/session.ts, src/respawn-controller.ts, src/screen-manager.ts
• Issue: Debug logs not disabled in production
• Fix: Use logger abstraction with levels
• Impact: Cleaner logs

15. Magic Numbers

• Files: src/session.ts:397, 428, src/respawn-controller.ts:614, 619
• Issue: Hardcoded timeout values
• Fix: Extract to named constants
• Impact: Easier tuning

---

Implementation Phases

Phase 1 (Critical) - Items #1-5

• Time: 8-12 hours
• Expected Gain: 30% performance

Phase 2 (Important) - Items #6-10

• Time: 6-8 hours
• Expected Gain: 15% performance

Phase 3 (Polish) - Items #11-15

• Time: 4-6 hours
• Expected Gain: 5% + code quality

---

Progress Tracking

Item	Status	Completed By	Notes
1	☐ Pending
2	☐ Pending
3	☐ Pending
4	☐ Pending
5	☐ Pending
6	☐ Pending
7	☐ Pending
8	☐ Pending
9	☐ Pending
10	☐ Pending
11	☐ Pending
12	☐ Pending
13	☐ Pending
14	☐ Pending
15	☐ Pending