---
title: Terminal UI (TUI)
description: Chat-first terminal control plane for orchestrating, monitoring, and steering Smithers workflows.
---

```bash
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.

```text
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

| Width | Behavior |
| --- | --- |
| >= 140 cols | Full three-column layout. Left rail 24 cols, right inspector 36--42 cols. |
| 100--139 cols | Inspector narrows to 28--32 cols. Less metadata in workspace rows. |
| 80--99 cols | Inspector becomes a toggleable overlay. Feed is the dominant pane. |
| < 80 cols | Single-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)

```text
|  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 type | Display |
| --- | --- |
| User | Compact text with optional attachment pills |
| Assistant | Markdown with code blocks, collapsible long sections |
| Tool | Collapsed by default, one-line summary with name/target/status/duration |
| Run | Compact badge with workflow name, run ID, step, elapsed, progress |
| Approval | Detaches from feed into an Action Bar above the composer to prevent scrolling off-screen |
| Artifact | File name, type, source workflow/run, open/diff/copy affordances |
| Diff | Structured diff card |
| Error | Red label, compact summary first, stack collapsed underneath |
| Summary | Assistant-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.

```text
[#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

| Key | Action |
| --- | --- |
| `Ctrl+O` | Open global command palette |
| `Tab` / `Shift+Tab` | Cycle focus: workspace rail, feed, inspector, composer |
| `Esc` | Dismiss 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+L` | Provider / model / profile picker |
| `Ctrl+R` | Prompt history search |
| `Ctrl+G` | Open composer in external editor |

### Composer

| Key | Action |
| --- | --- |
| `Enter` | Send |
| `Alt+Enter` | Queue follow-up |
| `Shift+Enter` / `Ctrl+J` | Newline |
| `@` | Unified context attach (file/image/directory/run/session) |
| `#` | Invoke workflow |
| `Ctrl+A` / `Ctrl+E` | Start / end of line |
| `Alt+B` / `Alt+F` | Word backward / forward |
| `Ctrl+W` / `Ctrl+U` / `Ctrl+K` | Kill word / line before / line after |

### Feed and lists

| Key | Action |
| --- | --- |
| `Up` / `Down` or `j` / `k` | Move selection |
| `g` / `G` | Jump to top / bottom |
| `PageUp` / `PageDown` | Page |
| `Space` | Expand / collapse selected item |
| `Enter` | Default action (open detail view) |
| `v` | Toggle verbose view |
| `o` | Open 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:

```text
+-- 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

| Command | Purpose |
| --- | --- |
| `/help` | Help |
| `/new` | New workspace |
| `/resume` | Resume workspace |
| `/tree` | Session tree |
| `/compact` | Compact feed |
| `/clear` | Clear feed |
| `/export` | Export feed to markdown/JSON |
| `/theme` | Switch theme |
| `/settings` | Settings |

### Smithers

| Command | Purpose |
| --- | --- |
| `/workflows` | Open workflow catalog |
| `/run` | Launch a workflow |
| `/runs` | Show live runs |
| `/approvals` | Show pending approvals |
| `/telemetry` | Telemetry board |
| `/triggers` | Trigger manager |
| `/datagrid` | SQL query browser |
| `/docs` | Search Smithers docs |
| `/attach-run` | Attach to a run |
| `/resume-run` | Resume a run |
| `/cancel-run` | Cancel a run |

### Provider

| Command | Purpose |
| --- | --- |
| `/provider` | Switch provider profile |
| `/mode` | Switch mode (operator/plan/direct) |
| `/budget` | Token budget |
| `/profiles` | Manage provider profiles |

### Context

| Command | Purpose |
| --- | --- |
| `/attach` | Attach file/context |
| `/detach` | Remove context |
| `/history` | Prompt history |
| `/editor` | Open 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](https://github.com/l3wi/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](/integrations/ecosystem).

### JJHub Cloud

[jjhub.tech](https://jjhub.tech) will have first-class Smithers support for hosted workflows with scheduling, observability, and team collaboration.

## Next steps

- [CLI Reference](/cli/overview) -- All CLI commands including `smithers tui`.
- [Monitoring & Logs](/guides/monitoring-logs) -- Observability with Grafana and Prometheus.
- [Debugging](/guides/debugging) -- Diagnosing workflow issues.