claude-hud/docs/adr/001-state-management.md

ADR 001: State Management Architecture

Status

Accepted

Context

The current app.tsx is 300+ lines with complex nested callbacks and multiple state variables scattered throughout. This makes the code:

• Hard to test
• Difficult to reason about
• Prone to race conditions
• Hard to maintain

We need a state management approach that:

1. Is simple enough for a metrics dashboard (not a full application)
2. Makes state transitions predictable
3. Is easily testable
4. Prevents unnecessary re-renders

Decision

Use custom hooks + useReducer, NOT XState or global Context.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         App.tsx                              │
│  (thin orchestration layer, <100 lines)                     │
├─────────────────────────────────────────────────────────────┤
│                      Custom Hooks                            │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│  │useHudState   │ │useToolStream │ │useContextTracking    │ │
│  │(main reducer)│ │(tool history)│ │(tokens, burn rate)   │ │
│  └──────────────┘ └──────────────┘ └──────────────────────┘ │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│  │useAgents     │ │useTodos      │ │useGitStatus          │ │
│  │(agent list)  │ │(todo list)   │ │(branch, changes)     │ │
│  └──────────────┘ └──────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Why NOT XState?

• Overkill for a dashboard with simple state
• Learning curve for contributors
• Additional dependency
• State machine formalism doesn't fit well with streaming events

Why NOT Context API?

• No prop drilling problem (flat component hierarchy)
• Global state not needed (components don't need to share state across deep trees)
• Adds complexity without benefit

Why Custom Hooks + useReducer?

• Encapsulation: Each hook owns its domain (tools, agents, context, etc.)
• Testability: Hooks can be tested in isolation with @testing-library/react-hooks
• Predictability: useReducer makes state transitions explicit and debuggable
• Performance: Each hook manages its own re-renders
• Simplicity: No new dependencies, standard React patterns

Example Structure

// hooks/useToolStream.ts
type ToolAction =
  | { type: 'TOOL_START'; payload: ToolEntry }
  | { type: 'TOOL_END'; payload: { id: string; duration: number } }
  | { type: 'CLEAR' };

function toolReducer(state: ToolEntry[], action: ToolAction): ToolEntry[] {
  switch (action.type) {
    case 'TOOL_START':
      return [action.payload, ...state].slice(0, 30);
    case 'TOOL_END':
      return state.map(t =>
        t.id === action.payload.id
          ? { ...t, status: 'done', duration: action.payload.duration }
          : t
      );
    case 'CLEAR':
      return [];
  }
}

export function useToolStream() {
  const [tools, dispatch] = useReducer(toolReducer, []);

  const startTool = useCallback((tool: ToolEntry) => {
    dispatch({ type: 'TOOL_START', payload: tool });
  }, []);

  const endTool = useCallback((id: string, duration: number) => {
    dispatch({ type: 'TOOL_END', payload: { id, duration } });
  }, []);

  return { tools, startTool, endTool };
}

Consequences

Positive

• Clear separation of concerns
• Easy to test each hook independently
• Standard React patterns (no learning curve)
• Explicit state transitions via reducer actions
• Each domain isolated (tools don't know about agents)

Negative

• More files to manage (one per hook)
• Need to coordinate between hooks in App.tsx
• No automatic state persistence (acceptable for session-scoped data)

Implementation Notes

1. Create tui/src/hooks/ directory
2. Extract state logic from app.tsx into domain hooks
3. App.tsx becomes thin orchestration layer
4. Each hook is independently testable