smithers

Drive Smithers, a durable control plane for long-running coding agents. Use when the user wants multi-step, long-running, crash-safe, or human-in-the-loop agent work: "orchestrate agents", "run a workflow", "implement this and review it", "keep iterating until tests pass", "plan then build", or anything that needs retries, approvals, replay, or evals across multiple AI steps. YOU (the agent) run Smithers on the user's behalf; it is not a GUI the human clicks. You are an ORCHESTRATOR: run long-running, multi-step, or background work *through* Smithers, not through your own ad-hoc subagents; spend your time observing the run and reporting.

Drive Smithers, a durable control plane for long-running coding agents. Use when the user wants multi-step, long-running, crash-safe, or human-in-the-loop agent work: "orchestrate agents", "run a workflow", "implement this and review it", "keep iterating until tests pass", "plan then build", or anything that needs retries, approvals, replay, or evals across multiple AI steps. YOU (the agent) run Smithers on the user's behalf; it is not a GUI the human clicks. You are an ORCHESTRATOR: run long-running, multi-step, or background work *through* Smithers, not through your own ad-hoc subagents; spend your time observing the run and reporting.

Query node/run lifecycle history by default; pass --raw for raw agent chunks and all event types. Run `smithers events --help` for usage details.

Output detailed run state. Structured output canonically uses nodes[].nodeId (legacy steps[].id remains for compatibility); --pool tallies attempt engine/model usage. Run `smithers inspect --help` for usage details.

Build a new Smithers workflow from a plain-English description. Dispatches to the create-workflow builder. Run `smithers init` first if the .smithers/ pack is not yet installed. Run `smithers make-workflow --help` for usage details.

Concise run health at a glance: verdict, node counts, agent/model mix, throughput, and the nodes gating progress. Run `smithers status --help` for usage details.

Watch explicitly named stale runs and auto-resume them; pass --all to opt into a workspace-wide sweep. Run `smithers supervise --help` for usage details.

Start a workflow execution. Omit the workflow (or pass --interactive) to pick one interactively and monitor it in the full-screen TUI; use -d for detached (background) mode. Run `smithers up --help` for usage details.

Discover local workflows from .smithers/workflows. Run `smithers workflow --help` for usage details.

Inspect and reclaim the worktrees Smithers created for <Worktree> lanes. Run `smithers worktree --help` for usage details.

Inspect and register subscriptions and api keys. Run `smithers agents --help` for usage details.

List and manage durable alert instances. Run `smithers alerts --help` for usage details.

Approve a paused approval gate. Auto-detects the pending node if only one exists. Run `smithers approve --help` for usage details.

Raise a blocking human-approval request from inside a run and wait for the decision. Use when blocked, uncertain, or about to do something irreversible — never guess. Run `smithers ask-human --help` for usage details.

Ask a question about Smithers using your installed agent and the Smithers MCP server. Run `smithers ask --help` for usage details.

File a smithers bug report to bug.smithers.sh; with --run it attaches the run's status, error, and last ~50 events (secrets scrubbed). Run `smithers bug --help` for usage details.

Safely halt agents and terminate a run. Run `smithers cancel --help` for usage details.

Create and start a one-task auto-hijacked chat run. Run `smithers chat-create --help` for usage details.

Show agent chat output for the latest run or a specific run. Run `smithers chat --help` for usage details.

Protocol commands for the Claude Code plugin: mirror runs into /workflows and notify the session. Run `smithers claude --help` for usage details.

Manage and run background schedule triggers. Run `smithers cron --help` for usage details.

Deny a paused approval gate. Run `smithers deny --help` for usage details.

Print DiffBundle as unified diff. Run `smithers diff --help` for usage details.

Print llms-full.txt (full docs bundle for LLMs) for this CLI version. Run `smithers docs-full --help` for usage details.

Print llms.txt (concise docs index for LLMs) for this CLI version. Run `smithers docs --help` for usage details.

Cancel all active runs. Like 'docker compose down' for workflows. Run `smithers down --help` for usage details.

Run a workflow over a JSON/JSONL eval suite and write a regression report. Run `smithers eval --help` for usage details.

Query run event history with filters, grouping, and NDJSON output. Run `smithers events --help` for usage details.

Create a branched run from a snapshot checkpoint (time travel). Run `smithers fork --help` for usage details.

Serve the multi-run Gateway RPC/WS control plane for workspace run state; unlike up --serve, this is not tied to one run. `smithers gateway status|stop` manages the workspace's running singleton. Run `smithers gateway --help` for usage details.

Render the workflow graph without executing it. Run `smithers graph --help` for usage details.

Open a directory's workspace in the Smithers UI: starts (or attaches to) the workspace Gateway and opens the MOST RECENT run's workflow UI; pass --workflow <id> to open a specific workflow UI directly. Run `smithers gui --help` for usage details.

Add Smithers to a local Hermes agent: register the MCP server and install the native Hermes plugin (slash commands, live status line, approval buttons). Alias for `mcp add --agent hermes`. Run `smithers hermes --help` for usage details.

Hand off the latest resumable agent session or conversation for a run. Run `smithers hijack --help` for usage details.

List and resolve durable human requests. Run `smithers human --help` for usage details.

Install the local Smithers workflow pack into .smithers/. Pass an optional prompt to also launch the create-workflow builder after init. Run `smithers init --help` for usage details.

Output detailed run state, including steps, agents, approvals, and outputs. Run `smithers inspect --help` for usage details.

Tail the event log of a specific run. Run `smithers logs --help` for usage details.

Build a new Smithers workflow from a plain-English description. Dispatches to the create-workflow builder. Run `smithers init` first if the .smithers/ pack is not yet installed. Run `smithers make-workflow --help` for usage details.

View and query cross-run memory facts. Run `smithers memory --help` for usage details.