Performance Profiling

Athena ships built-in profiling tooling for the Ink TUI. Use it when investigating render slowdowns, high GC pressure, or latency spikes in the event feed.

Quick Start

npm run perf:tui -- -- --sessions

Then reproduce the lag (for example: hold arrow-down in the session picker, then type quickly in the input bar) for 20–60 seconds, then exit with Ctrl+C.

Artifacts are written to .profiles/:

.profiles/
  athena-<timestamp>.cpuprofile    # Node.js CPU profile — open in Chrome DevTools
  node-trace-<timestamp>.json      # Node trace events
  tui-perf-<timestamp>.ndjson      # App-level instrumentation log (slow inputs, React commits, event-loop delay)

Focused Modes

npm run perf:cpu   -- -- --sessions   # CPU profile only
npm run perf:trace -- -- --sessions   # Node trace events only
npm run perf:heap  -- -- --sessions   # Heap / memory profiling

App Instrumentation Controls

perf:tui sets ATHENA_PROFILE=1 automatically. Additional environment variables:

Variable	Default	Description
`ATHENA_PROFILE_SLOW_MS`	`8`	Threshold in ms for logging slow operations
`ATHENA_PROFILE_INPUT_SLOW_MS`	`4`	Threshold in ms for logging slow input handlers
`ATHENA_PROFILE_INPUT_ALL`	—	Set to `1` to log every input handler (high volume)
`ATHENA_PROFILE_LOOP_MS`	`1000`	Event-loop sample interval in ms
`ATHENA_PROFILE_LOG`	—	Custom path for the NDJSON profiling log

Example with full input trace:

ATHENA_PROFILE_INPUT_ALL=1 npm run perf:tui -- -- --sessions

Inspecting Results

CPU profile — Open *.cpuprofile in Chrome DevTools → Performance panel → Load profile. Look for hot functions in the call tree. Common offenders in Athena:

stringWidth — called per-cell in the feed render hot path
ANSI tokenization — called per event row
React reconciliation in Ink — look for unnecessary re-renders triggered by context changes

Trace events — Open node-trace-*.json in chrome://tracing or about:tracing.

App log — Inspect top slow paths:

rg '"type":"(slow.op|input.handler|react.commit|event_loop.sample)"' .profiles/tui-perf-*.ndjson

Common Performance Issues

Symptom	Likely cause	Where to look
Feed drops frames at high rate	`stringWidth` in render hot path	`src/ui/layout/buildBodyLines.ts`
High GC pressure, many events	Objects created per-event not pooled	`src/core/feed/mapper.ts`
Slow session resume	SQLite `feed_events` query missing index	`src/infra/sessions/schema.ts`
Input lag when typing	Slow input handler in `useFeedKeyboard`	`src/ui/hooks/useFeedKeyboard.ts`
React re-renders on every event	Context selector not narrowly scoped	`src/app/providers/RuntimeProvider.tsx`