OpenTUI Debug

File-based debugging for OpenTUI apps since console.log output is captured by the TUI's debug overlay.

Quick Start

Log from components:

import { logDebug } from "./utils/debug.ts";

logDebug("render", { width, height, scrollOffset });

Agent reads the log:

read /path/to/project/debug.log

When to Use

Use when:

• •console.log doesn't appear in terminal (captured by OpenTUI)
• •Need to trace state changes across renders
• •Debugging scroll behavior, layout calculations
• •Analyzing key input handling

Setup (Already in Project)

• •src/utils/debug.ts - Logger utility
• •debug.log - Output file (project root, gitignored)
• •Auto-clears on app start

API

logDebug(label: string, data: unknown): void

Logs are appended with timestamps:

[2026-02-06T04:35:04.309Z] label:
{
  "key": "value"
}

Best Practices

1. •Log state changes in useEffect
2. •Log key presses in useKeyboard handlers
3. •Log calculated values (visible rows, scroll offsets)
4. •Restart app after adding debug points (logger initializes on import)

Example

useKeyboard((key) => {
  logDebug("key", { name: key.name, mode: currentMode });
  // ... handle
});

useEffect(() => {
  logDebug("scroll", { offset, maxScroll, visible: rows.length });
}, [offset]);

Troubleshooting