critique: Instructions file for Codex

opentui

opentui is the framework used to render the tui, using react.

IMPORTANT! before starting every task ALWAYS read opentui docs with curl -s https://raw.githubusercontent.com/sst/opentui/refs/heads/main/packages/react/README.md

ALWAYS!

using unreleased opentui versions

to use a pkg.pr.new preview URL for opentui, get the last commit hash (40 chars always) from PR https://github.com/anomalyco/opentui/pull/536:

gh pr view 536 -R anomalyco/opentui --json commits --jq '.commits[-1].oid[:40]'

then use it in package.json:

https://pkg.pr.new/anomalyco/opentui/@opentuah/core@<hash>
https://pkg.pr.new/anomalyco/opentui/@opentuah/react@<hash>

YOU MUST ALWAYS use the commit hash 40 characters long when changing the pkg.pr.new url! not the pr number!

if the commit hash url does not work it means it is still building. ignore the pkg.pr.new comment with the pr number in the install script. you MUST use the url with the commit hash.

bun

NEVER run the interactive TUI (e.g. bun run src/cli.tsx without arguments). It will hang. Instead ask the user to run it.

The web command is safe to run - it generates HTML and exits:

bun run src/cli.tsx web

NEVER use tsc --noEmit in this repo. Always run emitting builds so cli/dist stays updated.

after every code change, run bun run build from cli/ to make sure it compiles. fix any type errors before moving on.

NEVER use require. just import at the top of the file with esm

use bun add to install packages instead of npm

React

NEVER pass function or callbacks as dependencies of useEffect, this will very easily cause infinite loops if you forget to use useCallback

NEVER use useCallback. it is useless if we never pass functions in useEffect dependencies

Try to never use useEffect if possible. usually you can move logic directly in event handlers instead

Rules

• if you need Node.js apis import the namesapce and not the named exports: import fs from 'fs' and not import { writeFileSync } from 'fs'
• DO NOT use as any. instead try to understand how to fix the types in other ways
• to implement compound components like List.Item first define the type of List, using a interface, then use : to implement it and add compound components later using . and omitting the props types given they are already typed by the interface, here is an example
• DO NOT use console.log. only use logger.log instead
• uses onInput not onChange. it is passed a simple string value and not an event object
• to render examples components use renderWithProviders not render
• ALWAYS bind all class methods to this in the constructor. This ensures methods work correctly when called in any context (callbacks, event handlers, etc). Example: