mytui

High-density session navigation, per-workspace configuration, complete trajectory inspection, notifications, tool timing, and animated visuals for the opencode TUI.

Features

• Rainbow logo — Per-character HSL rainbow gradient across the OPENCODE ASCII art on the home screen
• Colored water droplets — Droplets fall from source blocks, colored by column position with fading alpha
• Animated sidebar — Pipboy ASCII art with scrolling vertical hue gradient
• Tool timing — Shows each running tool's start time, elapsed time, and a long-running/stuck hint in the sidebar
• Windows notifications — Alerts when permission approval or an answer is needed, and when a tool may be stuck
• Session board — A full-screen card board grouped by status, with sessions collected across different workspaces
• Workspace config manager — View and toggle tools, MCP servers, and skills in each workspace's OpenCode config
• Trajectory viewer — Inspect every stored message, part, tool call, reasoning part, change, control event, and descendant session without invoking a model

Session Board

Enter /board in opencode to open the full-screen session board. Sessions are grouped by workspace instead of being mixed together. The workspace path is its only heading and is compacted only when it gets too long. Every panel shows aggregate state, session counts, and last update time; its session cards are sorted by attention, working, retry/error, and idle state. Workspaces get stable individual accent colors, while compact session cards use semantic status colors and wrap into a dense grid. Session cards retain the session title, Agent/model, state, and last update time. The single-line control bar shows live counts for attention, working, retry, and idle sessions without spending another row per status.

Click a card to switch to that session. Hovering or keyboard navigation highlights the target; the session you came from has a solid dot. Use j/k or the arrow keys to move between cards and Enter to open one. Press / to search titles, workspace paths, Agents, models, and status words; press f to cycle the status filter, z to collapse or expand all workspaces, n to create a conversation in the selected workspace, c to manage its OpenCode config, and Shift+N to create a workspace. Click any workspace heading to collapse only that group. Esc clears an active search/filter first, then returns to the previous screen. Press r to rename the selected session or a to archive it after confirmation; archiving hides it without deleting its history. Press ? at any time to see the complete shortcut reference. Press Ctrl+B from any TUI page to return directly to the board. The shortcut is configurable with boardKeybind.

The card carries its own directory and workspace identity, so sessions from different projects and workspaces can live on the same board and still open in the correct place.

The board can hide sessions older than a configured age and workspaces whose directories no longer exist. Click New Workspace to enter a folder path: mytui creates the folder when necessary, creates an OpenCode session there, and opens it. Every existing workspace also has a New Conversation action that creates and opens another session without creating a new folder. Set boardOnStartup to true to make a plain opencode launch open the board first.

Workspace Config Manager

Select a workspace on /board and press c, click Config, or run /workspace-config from a session. The full-screen manager combines the effective runtime catalogs with the workspace file so inherited and workspace-specific states are visible together. Use j/k or the arrow keys to select an entry, Space or Enter to toggle it, / to search, f to switch between tools, MCP servers, and skills, and r to refresh.

Changes use OpenCode's native configuration shapes:

• Tools write tools.<id>: true|false.
• MCP servers write mcp.<id>.enabled: true|false.
• Skills write permission.skill.<id>: "allow"|"deny".

The manager prefers an existing opencode.jsonc, falls back to an existing opencode.json, and creates opencode.jsonc only when neither exists. It parses the latest file contents before every change, preserves JSONC comments and trailing commas, and writes through a same-directory temporary file followed by an atomic rename. Invalid files and files larger than 2 MiB are shown as errors and are not overwritten. The overview intentionally avoids rendering raw config values such as MCP environment variables or headers that may contain secrets.

Trajectory Viewer

Enter /trajectory (alias /trace) while viewing a session to open the local, full-screen trajectory viewer. Opening it does not invoke a model or consume model tokens. By default, it recursively loads every descendant session, detects session cycles, and fails clearly if the configured session limit is exceeded.

Use j/k or the arrow keys to select messages and Enter to expand them. / searches all stored data, including content hidden in collapsed tool inputs and outputs, system prompts, reasoning, paths, and metadata. Stored message.info.system values appear as their own system block and are included explicitly in HTML and Markdown exports. Press f to cycle through conversation, tool, reasoning, change, and control-event filters; a expands or collapses all messages; x reveals raw JSON; e writes a fully offline HTML export; and r refreshes the trajectory. Esc clears search/filter state before returning to the session.

“Complete” means all message info, parts, and descendant sessions stored and returned by the OpenCode session API. It cannot recover provider-hidden reasoning or system instructions that OpenCode/provider APIs did not store and return, nor deleted data. Unknown and future part fields remain available in raw JSON and exports. Exports may contain prompts, reasoning, tool inputs/outputs, paths, and other sensitive data; they stay local, are never uploaded automatically, and default to .opencode/trajectory/ inside the session directory. Do not commit or share them without reviewing their contents.

The trajectory viewer is built into mytui. If @forget2save/opencode-trajectory/tui is also present in your TUI plugin list, remove one of the two entries to avoid duplicate /trajectory commands.

Custom ASCII Art

You can override the default ASCII art with your own:

1. Create the directory ~/.config/opencode/mytui/
2. Place one or both of these files:
   • home.txt — replaces the home screen logo
   • side.txt — replaces the sidebar art
3. Restart opencode

Each file should contain rows of ASCII art, one line per row. Use █ for "solid" blocks (which act as droplet sources on the home screen). Generate art at patorjk.com/taag.

The plugin also installs a mytui-art skill that teaches the AI how to generate and configure custom ASCII art. Just ask the AI to customize your opencode logo.

Install

CLI:

opencode plugin -g @forget2save/mytui

Manual — add to ~/.config/opencode/tui.jsonc:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["@forget2save/mytui"]
}

Config

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    ["@forget2save/mytui", {
      "enabled": true,
      "sidebar": true,
      "toolTiming": true,
      "sessionBoard": true,
      "workspaceConfig": true,
      "boardKeybind": "ctrl+b",
      "trajectory": true,
      "trajectoryIncludeChildSessions": true,
      "trajectoryMaxSessions": 500,
      "trajectoryOutputDirectory": ".opencode/trajectory",
      "boardOnStartup": false,
      "boardLimit": 48,
      "boardRefreshSeconds": 5,
      "boardSessionMaxAgeDays": 30,
      "boardSessionsPerWorkspace": 12,
      "boardHideInvalidWorkspaces": true,
      "boardAllowCreateWorkspace": true,
      "boardAllowCreateSession": true,
      "boardColorful": true,
      "boardCardWidth": 30,
      "boardPathMaxLength": 72,
      "boardShowSessionMeta": true,
      "boardCollapseIdleWorkspaces": true,
      "boardKeyboardNavigation": true,
      "boardAllowSessionManagement": true,
      "boardNewWorkspaceRoot": "C:\\Users\\me\\Projects",
      "notifications": true,
      "toolTimeoutSeconds": 300
    }]
  ]
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable the plugin | | sidebar | boolean | true | Show the animated sidebar art | | toolTiming | boolean | true | Show start time and elapsed time for running tools | | sessionBoard | boolean | true | Enable the full-screen /board session board | | workspaceConfig | boolean | true | Enable per-workspace /workspace-config management from the board | | boardKeybind | string | ctrl+b | Global shortcut that opens the board; use none to disable | | trajectory | boolean | true | Enable the direct /trajectory (/trace) full-screen viewer | | trajectoryIncludeChildSessions | boolean | true | Recursively include all descendant sessions | | trajectoryMaxSessions | number | 500 | Maximum sessions loaded before failing clearly (1–10,000) | | trajectoryOutputDirectory | string | .opencode/trajectory | Validated export directory, relative to the session directory or absolute | | boardOnStartup | boolean | false | Open the board when opencode starts on its home screen | | boardLimit | number | 48 | Maximum number of recent top-level sessions shown (4–200) | | boardRefreshSeconds | number | 5 | Automatic board refresh interval in seconds (2–60) | | boardSessionMaxAgeDays | number | 30 | Hide sessions older than this many days; 0 disables the age filter | | boardSessionsPerWorkspace | number | 12 | Maximum recent sessions per workspace; 0 disables this limit | | boardHideInvalidWorkspaces | boolean | true | Hide workspaces whose directory no longer exists | | boardAllowCreateWorkspace | boolean | true | Show the New Workspace action | | boardAllowCreateSession | boolean | true | Show New Conversation on every valid workspace | | boardColorful | boolean | true | Give every workspace a stable individual accent color | | boardCardWidth | number | 30 | Compact session card width in terminal columns (24–60) | | boardPathMaxLength | number | 72 | Maximum displayed workspace path length before middle compaction (24–160) | | boardShowSessionMeta | boolean | true | Show Agent and model on compact session cards | | boardCollapseIdleWorkspaces | boolean | true | Start with idle workspaces collapsed, except the current session's workspace | | boardKeyboardNavigation | boolean | true | Enable j/k, arrow-key, and Enter card navigation | | boardAllowSessionManagement | boolean | true | Enable rename (r) and confirmed archive (a) actions on the selected session | | boardNewWorkspaceRoot | string | user home | Base directory used for relative new-workspace paths | | notifications | boolean | true | Master switch for system notifications | | permissionNotifications | boolean | true | Notify when permission approval is required | | questionNotifications | boolean | true | Notify when the agent is waiting for an answer | | longToolNotifications | boolean | true | Notify once when a tool exceeds the timeout | | toolTimeoutSeconds | number | 300 | Seconds before a running tool is considered potentially stuck (minimum 10) |

On Windows, the plugin displays title and body through a native notification-area popup, so it does not depend on Windows Terminal, OSC support, or terminal focus. OpenCode's attention service is still used for sounds. On other platforms, system notifications use OpenCode's terminal-mediated attention service. Make sure attention.enabled is enabled in tui.jsonc; enable attention.notifications for the non-Windows terminal notification path.

Requirements

• opencode >= 1.16.0

OpenTUI is pinned to the verified 0.4.5 release so development, packaging, and runtime installations all use the same renderer version.

@opencode-ai/plugin is only used for development-time types and is deliberately not installed at runtime, preventing its transitive peer dependencies from selecting a different OpenTUI release family.

License

MIT