Skip to main content
smithers tui
The TUI is a chat-first orchestration console. The default surface is a unified activity feed and composer, not a dashboard. Monitoring, approvals, and telemetry are visible without leaving the main workspace.

​
Product stance

Smithers TUI complements the CLI. Every meaningful UI action maps to a Smithers API or CLI operation, preserving the same durable, scriptable mental model. The TUI is not a full replacement for Claude Code, Codex CLI, Gemini CLI, or Amp. It is not a direct-edit harness by default. It is the orchestration layer above harnesses and API providers.

​
Shell layout

The shell has four regions: workspace rail, activity feed, inspector, and composer. 
Smithers  repo: api  workspace: auth-fix  profile: Claude+SDK  mode: operator  2 runs  1 approval   Ctrl+O actions

|  auth refactor        [CC]  .1         12:41  You       Build a reusable Smithers workflow for auth fixes.
   docs sync            [AI]   v         12:41  Smithers  Plan:
!  pr review            [SM]  A1                   - inspect existing .smithers/workflows
   incident triage      [GM]   x                   - factor shared retry and review steps
                                                   - launch #auth-fix over current diff

                                              12:42  Run       auth-fix  a93f  running  validate -> patch  3/7
                                              12:43  Tool      smithers.workflows.read  .smithers/workflows/review-pr.tsx  18ms
                                              12:44  Approval  Push generated patch to workspace branch?
                                                               [Enter] open   [a] approve   [d] deny
                                              12:45  Artifact  .smithers/workflows/auth-fix.tsx

[#auth-fix] [@src/auth.ts] [@README.md]  Build it to be reusable, not one-off.
budget 18k ctx   Enter send   Alt+Enter queue   Ctrl+G editor

​
Adaptive layouts

WidthBehavior
>= 140 colsFull three-column layout. Left rail 24 cols, right inspector 36—42 cols.
100—139 colsInspector narrows to 28—32 cols. Less metadata in workspace rows.
80—99 colsInspector becomes a toggleable overlay. Feed is the dominant pane.
< 80 colsSingle-pane mode. Workspace switcher and inspector are modal overlays.

​
Workspaces

A workspace is the top-level unit of activity. It contains a title, repo/cwd, current provider profile, mode, feed history, queued messages, linked runs, pinned context, and approval state. The left rail shows all open workspaces. Each row displays:
  • State marker (| active, ! attention, . running)
  • Title
  • Provider tag ([CC], [SM], [AI], [GM], [CX]) — progressively disclosed (hidden until hover/focus in standard layouts)
  • Compound Status badge (combines unread/approval into clear priority icons)
|  auth refactor        [CC]  .1
   docs sync            [AI]   v
!  pr review            [SM]  A1
   incident triage      [GM]   x
Workspace actions: create, switch, close, archive, rename, pin, duplicate, fork from current. Switching workspaces takes under 100ms. Active run and approval badges update without manual refresh.

​
Activity feed

The center pane is a unified activity feed that mixes all orchestration activity:
Item typeDisplay
UserCompact text with optional attachment pills
AssistantMarkdown with code blocks, collapsible long sections
ToolCollapsed by default, one-line summary with name/target/status/duration
RunCompact badge with workflow name, run ID, step, elapsed, progress
ApprovalDetaches from feed into an Action Bar above the composer to prevent scrolling off-screen
ArtifactFile name, type, source workflow/run, open/diff/copy affordances
DiffStructured diff card
ErrorRed label, compact summary first, stack collapsed underneath
SummaryAssistant-generated summaries for long activity blocks
The feed streams incrementally and auto-scrolls unless you manually scroll away. A LIVE / PAUSED indicator appears in the feed header. To prevent scroll-blindness, active long-running workflows pin a sticky status header tracking progress, and related tool events are grouped with vertical ASCII spines.

​
Empty states

New workspaces avoid the “blank terminal” syndrome by rendering a non-persistent Welcome Bento Board in the feed area. It displays current repo git status and proposes 3 suggested actions based on the repository heuristcs (e.g. noticing a package.json and suggesting a test workflow). This board naturally scrolls away once feed items occur.

​
Inspector

The right rail shows details for the currently selected feed item. The inspector is a dynamic, context-sensitive precision surface. Instead of showing persistent empty tabs, the pane’s title and contents morph based entirely on the selection. A breadcrumb (e.g., Inspector • Run a93f or Inspector • src/auth.ts) grounds the user. Depending on the selection, the inspector can render:
  • Run — run graph, status, steps, cost
  • Context — pinned context items, token budget
  • Workflow — schema, last runs, provider hints
  • Diff — file diffs
  • Logs — timestamped lifecycle events
  • Details — raw output, structured output, scorer results
The inspector reacts to the current feed selection immediately. Selecting a run item shows the run graph. Selecting a workflow mention shows schema and last runs. Selecting an attachment shows preview and token estimate.

​
Composer

The composer is a small command desk at the bottom of the shell. 
[#review-pr] [@src/auth.ts] [@README.md] [+2]
Build a reusable auth-fix workflow and run it against current diff.
budget 18k ctx    Enter send    Alt+Enter queue    Ctrl+G editor
Features:
  • Multiline input (auto-grows up to 6 rows, then scrolls)
  • @ unified mentions for attaching files, directories, images, workspaces, sessions, and runs
  • # invokes workflows (opens a fuzzy workflow picker)
  • Slash commands (/run, /workflows, /approvals, etc.)
  • Queued follow-up messages with Alt+Enter
  • Large paste guard — detects large paste and offers attach-as-file, inline, summarize, or cancel
  • Draft preserved while switching workspaces

​
Keyboard model

​
Global

KeyAction
Ctrl+OOpen global command palette
Tab / Shift+TabCycle focus: workspace rail, feed, inspector, composer
EscDismiss overlay, abort transient action, return focus toward composer
?Show shortcuts/help for current context
.Open contextual action menu for selected item
/Search current pane (when composer is not focused)
Ctrl+LProvider / model / profile picker
Ctrl+RPrompt history search
Ctrl+GOpen composer in external editor

​
Composer

KeyAction
EnterSend
Alt+EnterQueue follow-up
Shift+Enter / Ctrl+JNewline
@Unified context attach (file/image/directory/run/session)
#Invoke workflow
Ctrl+A / Ctrl+EStart / end of line
Alt+B / Alt+FWord backward / forward
Ctrl+W / Ctrl+U / Ctrl+KKill word / line before / line after

​
Feed and lists

KeyAction
Up / Down or j / kMove selection
g / GJump to top / bottom
PageUp / PageDownPage
SpaceExpand / collapse selected item
EnterDefault action (open detail view)
vToggle verbose view
oOpen artifact/diff/log in pager or external viewer
/Filter/search within the current pane

​
Destructive actions

No global single-key kill/approve while unfocused. Approval actions only appear inside the approval context. Confirmation dialogs always show the exact target. A per-workspace “always allow” path exists for repetitive safe actions.

​
Modes

The TUI supports three operating modes, switchable via /mode or Ctrl+L:

​
Operator (default)

The assistant prefers creating, modifying, and reusing Smithers workflows over direct file edits:
  1. Inspect existing .smithers/workflows/ first
  2. Reuse or refactor shared Smithers components
  3. Scaffold or edit workflows/scripts in .smithers/
  4. Launch durable runs for non-trivial work
  5. Monitor and report results
  6. Use cheaper API providers for broad analysis
  7. Escalate to harness-backed workers only when needed
  8. Ask before direct edits outside .smithers/

​
Plan

Read-only. No file writes, no destructive shell, no workflow execution without confirmation.

​
Direct

Direct repo edits allowed. Still encourages Smithers scripts where useful but does not block one-off edits.

​
Provider routing

A provider profile routes work by task class. Example:
  • Repo scan -> AI SDK / cheap model
  • Workflow generation -> API strong model
  • Repo implementation -> Claude Code or Codex harness
  • Final summary -> cheap model
The current provider and routing policy are visible in the top line and editable via /provider and /profiles.

​
Workflow catalog

Type # in the composer to open the workflow picker: 
+-- Workflows ----------------------------------------------------------------+
| > review-pr            PR review against current diff         last v 4m      |
|   auth-fix             Reusable auth remediation flow         last x 1h      |
|   docs-refresh         Refresh docs and changelog             last v 1d      |
|                                                                              |
| review-pr                                                                    |
|   input: { target?: string, diff?: boolean, push?: boolean }                |
|   providers: SDK analyze -> Claude Code patch -> SDK summary                 |
|   tags: review, reusable, repo                                              |
+------------------------------------------------------------------------------+
The catalog auto-discovers workflows from .smithers/workflows/. Features:
  • Favorites and recents
  • Fuzzy search by ID, tags, description, provider hints
  • Input schema summary
  • Last-run status, duration, success rate
  • Launch form generated from schema when possible

​
Run monitoring

Run cards in the feed show:
  • Workflow name, run ID, provider
  • Elapsed time, step count, progress bar
  • Latest node, approval state
  • Retries, failures, token/cost summary
The inspector supports deep run inspection:
  • Overview and DAG/step graph
  • Node attempts
  • Logs and chat transcript
  • Artifacts and scorer results
  • Raw/structured output
  • Retry, resume, and cancel actions
Navigate from a feed item to the deep run inspector in one action. Attach to any active run. Run state persists if the TUI exits.

​
Notifications

Events that trigger notifications:
  • Approval needed
  • Run failed or completed
  • Provider disconnected
  • Queued message delivered
Notifications appear as in-app badges on the workspace rail. Terminal bell, OSC notifications, and desktop notifications are available. Notifications are suppressed when the relevant workspace is focused.

​
Slash commands

​
Core

CommandPurpose
/helpHelp
/newNew workspace
/resumeResume workspace
/treeSession tree
/compactCompact feed
/clearClear feed
/exportExport feed to markdown/JSON
/themeSwitch theme
/settingsSettings

​
Smithers

CommandPurpose
/workflowsOpen workflow catalog
/runLaunch a workflow
/runsShow live runs
/approvalsShow pending approvals
/inboxUnified attention queue (alerts + approvals + human requests)
/telemetryTelemetry board
/triggersTrigger manager
/datagridSQL query browser
/docsSearch Smithers docs
/attach-runAttach to a run
/resume-runResume a run
/cancel-runCancel a run

​
Provider

CommandPurpose
/providerSwitch provider profile
/modeSwitch mode (operator/plan/direct)
/budgetToken budget
/profilesManage provider profiles

​
Context

CommandPurpose
/attachAttach file/context
/detachRemove context
/historyPrompt history
/editorOpen external editor

​
Command palette

Press Ctrl+O to open the global command palette. All slash commands and contextual actions are searchable here. Natural language also works — type what you want and the assistant interprets it.

​
Persistence and recovery

The TUI survives:
  • Accidental exits (workspace restore on relaunch)
  • TTY resize
  • Provider disconnects (reconnect automatically)
  • Broker crashes (workflow runs continue independently)
  • Large paste mistakes (paste guard dialog)
Persisted state includes: last active workspace, composer draft, attachment chips, inspector tab, follow mode, selected feed entry, pending queued messages, and broker reconnect cursor.

​
Monitoring with Claude Code

Smithers persists all state to SQLite and exposes it through the CLI, so Claude Code can query status and report progress without interrupting execution. Set up a recurring health check with /cron: 
/cron 10m Check the smithers workflow running in this directory.
Run `smithers ps` to see active runs, then `smithers inspect <run-id>`
for the latest run. Summarize what tasks have completed, what's currently
running, any failures, and overall progress. Keep it brief.
With --hot, Smithers watches for file changes and hot-reloads the workflow definition. Claude Code can edit prompts, swap agents, or restructure the JSX tree mid-run. In-flight tasks keep their original code; new tasks use the updated definition. Other patterns:
  • Ad hoc inspection — Read the Smithers database and explain a failed run
  • Approval handling — Run smithers approve or smithers deny based on criteria
  • Live tuning — With --hot, tweak prompts or switch models mid-run
  • Post-run analysis — Summarize outputs and suggest next steps

​
Beyond the terminal

​
Burns

Burns is a workspace-first local control plane for Smithers. React web app, ElectroBun desktop shell, and headless CLI for authoring, running, and supervising workflows. See Ecosystem.

​
JJHub Cloud

jjhub.tech will have first-class Smithers support for hosted workflows with scheduling, observability, and team collaboration.

​
Next steps