Documentation Index
Fetch the complete documentation index at: https://smithers.sh/llms.txt
Use this file to discover all available pages before exploring further.
bunx smithers-orchestrator tui
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 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
| 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 holds 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
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 |
LIVE / PAUSED indicator appears in the feed header. Long-running workflows pin a sticky status header tracking progress, and related tool events group 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 repository heuristics (e.g. spotting a package.json and suggesting a test workflow). The board scrolls away once feed items appear.
Inspector
The right rail shows details for the currently selected feed item.
A dynamic, context-sensitive precision surface. Instead of persistent empty tabs, the pane’s title and contents morph with the selection. A breadcrumb (e.g., Inspector • Run a93f or Inspector • src/auth.ts) grounds the user.
Depending on the selection, the inspector renders:
- 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
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
- 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
Three operating modes, switchable with /mode or Ctrl+L:
Operator (default)
The assistant prefers creating, modifying, and reusing Smithers workflows over direct file edits:
- Inspect existing
.smithers/workflows/ first
- Reuse or refactor shared Smithers components
- Scaffold or edit workflows/scripts in
.smithers/
- Launch durable runs for non-trivial work
- Monitor and report results
- Use cheaper API providers for broad analysis
- Escalate to harness-backed workers only when needed
- 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 with /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 |
+------------------------------------------------------------------------------+
.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 across 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 |
/inbox | Unified attention queue (alerts + approvals + human requests) |
/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 works too — 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 queries status and reports 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.
--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