tui review

[olafura]

What Changed

Added a complete version of a tui. This meant to demonstrate the tui in it's more completed state before I will split it up into smaller pieces following the guidelines of the contribution documentation. It's hard to know the worth if it's in smaller pieces because it can just seem like a lost cause.

Why

I have a linux box running all the time and I do use the port forwarding capabilites but sometimes when there is a poor connection or when I need to do things quickly it's way faster going to a terminal tab. I am probably using the tui 30% of the time now sometimes fluxuating to 50%.

UI Changes

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

High Risk
Large new surface area touching authentication, WebSocket RPC, terminal lifecycle, and workspace file reads, though image base64 reads are gated and the change set includes substantial tests.

Overview
Adds a terminal UI for the already-running local T3 Code server so you can drive threads over SSH without port forwarding. The new t3 tui subcommand (Node) validates the persisted server, issues a short-lived bearer session, spawns a Bun subprocess running @t3tools/tui (OpenTUI + React), and mints WebSocket tickets over Node IPC. Release builds bundle apps/tui into dist/tui with a check that blocks unresolved runtime imports.

The TUI mirrors much of the web shell: responsive sidebar, multiline composer (images from clipboard/paths), command palette, approvals, terminal drawer, source-control panel, new-thread/project flows, and settlement actions—with extensive layout and interaction tests.

Server changes that support the TUI (and other clients): terminal.list plus listing/closing persisted terminal tabs after restart; projects.readFile optional base64 encoding limited to image paths and size caps; PTY spawn env sets COLORTERM=truecolor; shared runningServer probing for live server detection (also used from pairing).

^{Reviewed by Cursor Bugbot for commit 748d9c9. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add a full terminal UI (TUI) for SSH access to the chat interface

• Introduces apps/tui as a new Bun-based TUI application built on OpenTUI, providing a terminal-rendered chat interface with sidebar, conversation timeline, composer, command palette, git panel, and terminal drawer.
• Adds a new opentui-image package implementing Kitty graphics protocol support (image transmission, Unicode placeholders, clipboard paste, tmux passthrough) and a React <Image> component.
• Extends the server with a tui CLI command (apps/server/src/bin.ts), a terminal.list WebSocket RPC, and TerminalManager.list to enumerate live and persisted terminal IDs per thread.
• Moves shared logic (terminalLinks, chatMessages, resolveBranchSelectionTarget) from web-only modules into shared packages so the TUI can consume them without duplicating code.
• Adds build pipeline changes: the server build now stages apps/tui/dist/index.js into dist/tui/index.js, validates it for unresolved imports, and unpacks it from the Electron asar on macOS/Linux.
• Risk: the TUI spawns a Bun subprocess via Node IPC; if Bun is not installed, users see a hint but the TUI is unavailable.

📊 Macroscope summarized 748d9c9. 86 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3b19391e-b78f-4ff3-aef4-8deaa7a73f26

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

🟡 Medium components/ThreadTerminalDrawer.tsx:207

When the user scrolls up in a terminal pane and presses ^O to copy, the clipboard receives the live tail instead of the scrollback text currently shown on screen. The copyRef getter calls readTerminalViewport(term), which always reads from buffer.viewportY (the live tail), but the pane renders from baseY - scrollOffsetRef.current when scrolled. Consider passing the current scrollOffsetRef.current into readTerminalViewport so the copied text matches the visible viewport.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/tui/src/components/ThreadTerminalDrawer.tsx around line 207:

When the user scrolls up in a terminal pane and presses `^O` to copy, the clipboard receives the live tail instead of the scrollback text currently shown on screen. The `copyRef` getter calls `readTerminalViewport(term)`, which always reads from `buffer.viewportY` (the live tail), but the pane renders from `baseY - scrollOffsetRef.current` when scrolled. Consider passing the current `scrollOffsetRef.current` into `readTerminalViewport` so the copied text matches the visible viewport.

[macroscopeapp]

🟡 Medium src/fileTree.ts:46

buildFileTree splits file.path only on /, so a path with backslashes like apps\web\src\index.ts is treated as a single filename instead of a nested directory tree. On Windows, this loses directory grouping, chain compaction, and collapse/expand behavior for changed files. The web tree normalizes \ to / before splitting; consider doing the same here.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/tui/src/fileTree.ts around line 46:

`buildFileTree` splits `file.path` only on `/`, so a path with backslashes like `apps\web\src\index.ts` is treated as a single filename instead of a nested directory tree. On Windows, this loses directory grouping, chain compaction, and collapse/expand behavior for changed files. The web tree normalizes `\` to `/` before splitting; consider doing the same here.

[macroscopeapp]

🟠 High src/attachmentImages.ts:54

load calls response.arrayBuffer() and allocates the full response body into memory before checking encoded.byteLength > maxEncodedBytes. When Content-Length is absent or understated (e.g. chunked transfer encoding), there is no early cap and the entire body is buffered into a Uint8Array regardless of maxEncodedBytes, so an oversized response can exhaust the process's memory — the size check only runs after the allocation has already happened. Consider reading the body incrementally with a running byte cap and aborting once it is exceeded, rather than buffering the complete response first.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/tui/src/attachmentImages.ts around line 54:

`load` calls `response.arrayBuffer()` and allocates the full response body into memory before checking `encoded.byteLength > maxEncodedBytes`. When `Content-Length` is absent or understated (e.g. chunked transfer encoding), there is no early cap and the entire body is buffered into a `Uint8Array` regardless of `maxEncodedBytes`, so an oversized response can exhaust the process's memory — the size check only runs after the allocation has already happened. Consider reading the body incrementally with a running byte cap and aborting once it is exceeded, rather than buffering the complete response first.

[macroscopeapp]

🟠 High src/models.ts:32

flattenModelOptions includes models from every provider regardless of its enabled/availability state, so disabled or unavailable providers appear in the picker. Selecting one causes thread creation or reply submission to fail because the runtime refuses to start turns against unavailable providers. Consider filtering providers to only enabled/available entries before iterating their models.

  for (const provider of providers) {
+    if (provider.enabled === false || provider.availability === "unavailable") continue;
    const providerLabel = provider.displayName ?? provider.driver ?? provider.instanceId;

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/tui/src/models.ts around lines 32-33:

`flattenModelOptions` includes models from every provider regardless of its `enabled`/`availability` state, so disabled or unavailable providers appear in the picker. Selecting one causes thread creation or reply submission to fail because the runtime refuses to start turns against unavailable providers. Consider filtering `providers` to only enabled/available entries before iterating their models.

[macroscopeapp]

🟡 Medium components/ChatView.layout.ts:90

composerRows can exceed the terminal height because composerChromeRows is added to editorRows without any cap. When composerChromeRows is large (e.g., a question with many options), composerRows grows beyond height, and the returned panesRows + composerRows + terminalRows + popoverRows + STATUS_ROWS exceeds the terminal height, breaking the allocation invariant and causing composer content to overlap. Consider clamping composerRows (or editorRows with chrome included) to the available rows so totals never exceed height.

  const terminalReserve = input.terminalOpen ? MIN_TERMINAL_DRAWER_ROWS : 0;
-  const editorBudget = Math.max(
-    1,
-    height - STATUS_ROWS - MIN_TIMELINE_ROWS - terminalReserve - chromeRows,
-  );
-  const editorRows = Math.max(
-    1,
-    Math.min(Math.floor(input.desiredEditorRows), COMPOSER_MAX_EDITOR_ROWS, editorBudget),
-  );
-  const composerRows = chromeRows + editorRows;
+  const composerBudget = Math.max(
+    0,
+    height - STATUS_ROWS - MIN_TIMELINE_ROWS - terminalReserve,
+  );
+  const maxEditorRows = Math.max(0, composerBudget - chromeRows);
+  const editorRows = Math.max(
+    1,
+    Math.min(Math.floor(input.desiredEditorRows), COMPOSER_MAX_EDITOR_ROWS, maxEditorRows),
+  );
+  const composerRows = Math.min(chromeRows + editorRows, composerBudget);

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/tui/src/components/ChatView.layout.ts around lines 90-98:

`composerRows` can exceed the terminal height because `composerChromeRows` is added to `editorRows` without any cap. When `composerChromeRows` is large (e.g., a question with many options), `composerRows` grows beyond `height`, and the returned `panesRows + composerRows + terminalRows + popoverRows + STATUS_ROWS` exceeds the terminal height, breaking the allocation invariant and causing composer content to overlap. Consider clamping `composerRows` (or `editorRows` with chrome included) to the available rows so totals never exceed `height`.

[macroscopeapp]

🟠 High workspace/WorkspaceFileSystem.ts:221

The base64 image-only gate checks input.relativePath (the user-supplied alias), so a workspace symlink like preview.png -> database.sqlite passes the chatImageMimeTypeForPath check while the resolved realTargetPath is opened and up to 10 MB of the non-image target is returned as base64. This defeats the restriction intended to prevent arbitrary binary workspace reads. Validate the resolved path (realTargetPath) or the actual file content instead of the requested alias.

Suggested change

	if (encoding === "base64" && chatImageMimeTypeForPath(input.relativePath) === null) {
	if (encoding === "base64" && chatImageMimeTypeForPath(realTargetPath) === null) {

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/src/workspace/WorkspaceFileSystem.ts around line 221:

The base64 image-only gate checks `input.relativePath` (the user-supplied alias), so a workspace symlink like `preview.png -> database.sqlite` passes the `chatImageMimeTypeForPath` check while the resolved `realTargetPath` is opened and up to 10 MB of the non-image target is returned as base64. This defeats the restriction intended to prevent arbitrary binary workspace reads. Validate the resolved path (`realTargetPath`) or the actual file content instead of the requested alias.

[macroscopeapp]

🟠 High scripts/tuiBundle.ts:1

OPAQUE_PACKAGE_REQUIRE requires ( immediately after the closing ) of createRequire(...), so lookups with whitespace between them (e.g. createRequire(import.meta.url) ("@xterm/headless")) are not detected — findUnresolvedTuiBundleImport returns null and the build passes while shipping a runtime dependency on unavailable node_modules. Additionally, PRIVATE_WORKSPACE_IMPORT only matches from, import(, and require( forms, so bare import "@t3tools/foo" and export { x } from "@t3tools/foo" also return null, letting unresolved private workspace packages through validation. Consider allowing optional whitespace/newlines between createRequire(...) and (, and adding import\s+ and export\s+.*from\s+ as recognized import forms.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/server/scripts/tuiBundle.ts around line 1:

`OPAQUE_PACKAGE_REQUIRE` requires `(` immediately after the closing `)` of `createRequire(...)`, so lookups with whitespace between them (e.g. `createRequire(import.meta.url) ("@xterm/headless")`) are not detected — `findUnresolvedTuiBundleImport` returns `null` and the build passes while shipping a runtime dependency on unavailable `node_modules`. Additionally, `PRIVATE_WORKSPACE_IMPORT` only matches `from`, `import(`, and `require(` forms, so bare `import "@t3tools/foo"` and `export { x } from "@t3tools/foo"` also return `null`, letting unresolved private workspace packages through validation. Consider allowing optional whitespace/newlines between `createRequire(...)` and `(`, and adding `import\s+` and `export\s+.*from\s+` as recognized import forms.

[macroscopeapp]

🟡 Medium components/ComposerPendingUserInputPanel.tsx:40

When a question has more options than the terminal has rows, the panel overflows the composer height and the later options plus the submit controls are clipped off-screen — including the option currently highlighted by optionIndex. The option list is rendered fully inside a flexShrink={0} column with no scroll window, and there is no length cap on the options array upstream, so a long list grows the panel beyond the available rows. Consider windowing the options around optionIndex (like a command palette) instead of mapping the entire array.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/tui/src/components/ComposerPendingUserInputPanel.tsx around line 40:

When a question has more options than the terminal has rows, the panel overflows the composer height and the later options plus the submit controls are clipped off-screen — including the option currently highlighted by `optionIndex`. The option list is rendered fully inside a `flexShrink={0}` column with no scroll window, and there is no length cap on the options array upstream, so a long list grows the panel beyond the available rows. Consider windowing the options around `optionIndex` (like a command palette) instead of mapping the entire array.

[macroscopeapp]

🟠 High src/gitActions.logic.ts:154

resolveGitQuickAction returns action: "commit_push" while labeling it "Push" on clean branches (no working-tree changes) that are ahead — both with an upstream (line 184) and without (line 158). gitActionNeedsCommitMessage("commit_push") is true, so the user is prompted for a commit message on a push-only operation, and the server runs a commit step with no changes to commit. These clean-ahead paths should return action: "push" instead.

     if (hasOpenPr || isDefaultRef) {
       return {
         kind: "run_action",
         label: "Push",
-        action: isDefaultRef ? "commit_push" : "push",
+        action: "push",
         disabled: false,
       };
     }
     return { kind: "run_action", label: "Push & create PR", action: "create_pr", disabled: false };

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/tui/src/gitActions.logic.ts around lines 154-163:

`resolveGitQuickAction` returns `action: "commit_push"` while labeling it `"Push"` on clean branches (no working-tree changes) that are ahead — both with an upstream (line 184) and without (line 158). `gitActionNeedsCommitMessage("commit_push")` is `true`, so the user is prompted for a commit message on a push-only operation, and the server runs a commit step with no changes to commit. These clean-ahead paths should return `action: "push"` instead.

[macroscopeapp]

🟡 Medium hooks/useKittyGraphicsSupport.ts:12

useKittyGraphicsSupport can permanently report false even after Kitty support is detected. If the CAPABILITIES event fires between the initial render (where manager.isSupported is read as false) and the useEffect that subscribes to it, that event is missed: supported stays false and no subsequent capability event is guaranteed. Inline images then stay disabled for the entire session. Re-read manager.isSupported right after registering the listener inside the effect (or use useSyncExternalStore) so the state always reflects the current value.

  React.useEffect(() => {
+    setSupported(manager.isSupported);
    const onCapabilities = () => {
      setSupported(manager.isSupported);
    };

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/tui/src/hooks/useKittyGraphicsSupport.ts around lines 12-13:

`useKittyGraphicsSupport` can permanently report `false` even after Kitty support is detected. If the `CAPABILITIES` event fires between the initial render (where `manager.isSupported` is read as `false`) and the `useEffect` that subscribes to it, that event is missed: `supported` stays `false` and no subsequent capability event is guaranteed. Inline images then stay disabled for the entire session. Re-read `manager.isSupported` right after registering the listener inside the effect (or use `useSyncExternalStore`) so the state always reflects the current value.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 4 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 748d9c9. Configure here.}

[cursor]

Stale list resurrects closed tabs

Medium Severity

A race condition can cause closed terminals to reappear in the tab strip. If a terminal is removed via metadata subscription, a concurrently resolving listTerminalIds request (which only adds IDs) can reintroduce it into knownTerminals.

 

^{Reviewed by Cursor Bugbot for commit 748d9c9. Configure here.}

[cursor]

Snapshot wipes persisted terminals

Medium Severity

A metadata snapshot replaces all of knownTerminals with live sessions only, dropping ids previously learned from terminal.list. That list fetch runs only when the selected thread changes, so after a websocket resubscribe persisted-only terminals disappear from discovery until the user switches threads.

Additional Locations (1)

• apps/tui/src/components/ChatView.tsx#L1937-L1998

 

^{Reviewed by Cursor Bugbot for commit 748d9c9. Configure here.}

[cursor]

Stale tab count leaves drawer open

Medium Severity

closeTerminal decides whether to close the drawer from render-time detailTabs length, while tab removal uses a functional update. Rapid closes of the last two tabs can both see a length greater than one, clear every tab, and leave the terminal drawer open with an empty tab strip.

 

^{Reviewed by Cursor Bugbot for commit 748d9c9. Configure here.}

[cursor]

Approvals report success on failure

Medium Severity

onApprove and onDecline always set a success status immediately and swallow RPC errors with an empty .catch. When the approval request fails, the UI still claims the prompt was approved or declined even though the server request remains open.

 

^{Reviewed by Cursor Bugbot for commit 748d9c9. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

15 blocking correctness issues found. Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}