opencode-ralph: Instructions file for Codex

AGENTS.md - Critical Operational Details

TypeScript Configuration

When using @opentui/solid, the jsxImportSource must be set to "@opentui/solid", NOT "solid-js". The plan.md incorrectly specifies solid-js but the actual requirement from the OpenTUI documentation is:

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "@opentui/solid"
  }
}

Additionally, a bunfig.toml preload is required:

preload = ["@opentui/solid/preload"]

Dependencies

The package.json uses @types/bun (modern approach) which doesn't require explicitly listing bun-types in the tsconfig's types array. The types are discovered automatically.

OpenTUI Configuration

When using @opentui/solid for CLI TUI rendering, use these render options:

render(
  () => <App />,
  {
    targetFps: 30,           // Balance between smoothness and CPU usage
    gatherStats: false,      // Disable stats gathering for performance
    exitOnCtrlC: false,      // Handle Ctrl+C manually via useKeyboard
    useKittyKeyboard: {},    // Enable Kitty keyboard protocol
  }
);

Critical pattern: Call renderer.disableStdoutInterception() immediately after useRenderer() to prevent OpenTUI from capturing stdout, which can interfere with logging.

Keyboard Handling

Known Issue: The onMount lifecycle hook in @opentui/solid does NOT fire reliably on Windows. Since useKeyboard registers its handler inside onMount, keyboard events may not work through OpenTUI's native keyboard handling.

Workaround: Implement a fallback stdin handler that activates after a timeout if no OpenTUI keyboard events are received:

// In src/index.ts
let keyboardWorking = false;
const keyboardTimeout = setTimeout(() => {
  if (!keyboardWorking && process.stdin.isTTY) {
    process.stdin.setRawMode(true);
    process.stdin.resume();
    process.stdin.on("data", (data) => {
      if (keyboardWorking) return; // OpenTUI took over
      const key = data.toString();
      if (key === "q" || key === "\x03") { /* quit */ }
      if (key === "p") { /* pause */ }
    });
  }
}, 5000);

// Pass callback to App to signal when OpenTUI keyboard works
onKeyboardEvent: () => { keyboardWorking = true; clearTimeout(keyboardTimeout); }