Troubleshooting

Each section starts with a symptom as you see it, gives the cause, and names what to do. Upgrade notes covers behaviour that changed between releases.

Install and typecheck

bun install prints warn: incorrect peer dependency for typescript. The warning comes from bun-ffi-structs, a dependency of OpenTUI that declares an older TypeScript peer range than Tooee projects use. Ignore the warning.

tsc reports error TS17004: Cannot use JSX unless the '--jsx' flag is provided. The file holds a component and tsconfig.json has no jsx option. Add "jsx": "react-jsx".

tsc reports Property 'content' does not exist on type 'SVGTextElementAttributes<SVGTextElement>'. TypeScript resolved <text> to the SVG element from the DOM types because jsxImportSource is missing. Add "jsxImportSource": "@opentui/react" next to jsx. Install shows the full file.

node_modules is over 300 MB after bun add @tooee/view. @tooee/view depends on @tooee/diff, which depends on hunkdiff. Hunk installs a binary for your platform, 158 MB on Linux x64, for a command-line tool that Tooee never runs. The size is disk only; there is no setting to change.

Pipes and stdin

tooee view, tooee ask, or tooee choose prints Unable to start Tooee: ENXIO: no such device or address, open '/dev/tty' and exits with code 2. When stdin or stdout is not a terminal, Tooee opens the controlling terminal, /dev/tty, in its place, and the process has none. A CI job, a cron job, or a harness that starts the command without a terminal gets this error. Run the command from a terminal. In tests, start it in a pseudo-terminal, as Testing shows.

A script that mounts View with runCliSession exits at once when you pipe content into it. runCliSession reads keys from process stdin by default, and guardTerminalHealth in @tooee/shell ends the session when that stream closes. A pipe closes as soon as its content is delivered. Pass the tty-if-piped policy, as launch() from @tooee/view does. The renderer then reads keys from /dev/tty and leaves stdin to the content provider:

import { runCliSession } from "@tooee/shell";
import { View, createStdinProvider } from "@tooee/view";
import type { ReactNode } from "react";

await runCliSession((): ReactNode => <View contentProvider={createStdinProvider()} />, {
  stdinPolicy: "tty-if-piped",
});

git diff | bun view-stdin.tsx draws the patch and q quits. When you also redirect the stdout of the script, add stdoutPolicy: "tty-if-redirected" so the screen draws on the terminal and stays out of the output. CLI reference lists the terminal channels of the tooee commands.

Keys

Escape does nothing under a test harness. OpenTUI enables the kitty keyboard protocol, under which a terminal sends Escape as \u001B[27u, and OpenTUI reads the bare 0x1b byte as Escape too. A harness that still drops the key can send the encoded form with writeRaw, as Testing shows.

A <leader> hotkey never fires. No leader is set. Tooee logs [tooee/commands] Hotkey "<leader>l" uses <leader> but no leader key is configured; the hotkey is disabled. once, and the renderer routes console output to the OpenTUI debug console, so press ctrl+shift+j to read it. Pass provider: { leader: "space" } to launchCli or runCliSession; The leader key covers it.

Copy and paste

The toast says Copy failed: no clipboard tool found (wl-copy, xclip or xsel). Tooee found no clipboard tool on PATH, or the tool exited with an error. Install one of the tools it looks for:

The tools are looked up with Bun.which on the PATH of the Tooee process, so a launcher that starts Bun with a reduced PATH loses the clipboard as well. The order in each row is the order Tooee tries. Keyboard basics lists the copy keys.

Dragging with the mouse selects text but copies nothing on macOS or Windows. Copy on select is on for Linux only, where it fills the primary selection. Set view.copyOnSelect to "clipboard" in the config to copy dragged text to the clipboard on any platform.

Images

An image draws as coloured blocks instead of pixels. OpenTUI picks the protocol from what the terminal reports: kitty graphics when the terminal supports it, sixel when it is supported and the cell size in pixels is known, and half-block characters otherwise. Inside tmux the answer is blocks. A terminal that answers no capability query, such as a scripted PTY, gets blocks too. Open the file in Kitty, Ghostty, or WezTerm outside tmux, or set protocol: "kitty" on the image content to force the protocol. Image lists the fields.

Syntax colours

A code file opens without colours. OpenTUI bundles grammars for typescript, javascript, markdown, and zig. createFileProvider assigns a language to 25 extensions, and the other 21 draw as plain text with a gutter. Files with a diff extension, or piped patches, open in the diff format, which Hunk colours on its own. Code and text covers the rule.

Terminal

After the session, git log or another pager prints 'unknown': I need something more specific. TERM is unset in the environment that ran the script, so less has no terminal description. Tooee neither sets nor clears TERM; the message appears in that environment with or without a Tooee session before the pager. Export TERM, for example TERM=xterm-256color, in the shell, the CI job, or the agent harness that runs the script.

Next

• Install
• Keyboard basics
• Testing
• CLI reference