Common workflows¶

Short recipes for the things you do with smelt. For every key and command, see Keybindings and Commands.

Point the agent at the right code¶

Type @ followed by a path and a fuzzy file picker opens. The file's contents are attached to your message:

explain @src/main.rs

Use as many @ references as you like. Attaching the same file twice won't send it twice.

Paste with Cmd+V (or your terminal's paste). Images are attached inline, which is handy for screenshots of UI bugs or design mock-ups, and multi-line text is collapsed into a single attachment.

For rules the agent should always follow in a project, put them in an AGENTS.md.

Review before it changes anything¶

Modes set how much the agent may do without asking. Press Shift+Tab to cycle them; the current one is shown in the status bar.

Start in a mode with --mode, and choose which modes the cycle includes with --mode-cycle. A good habit for bigger changes is to start in Plan, read the plan, then switch to Apply.

When a tool needs permission, a confirm dialog shows what it wants to do, with a diff for edits. Approve once, for the session, or for the workspace. Session and workspace approvals save you from confirming the same safe call again and again, for example every git status in a repo you trust. Press Tab to attach a note to your decision that the agent will see.

See Permissions for the rules behind each mode and approval scope, and Tools for what the agent can call.

Run hands-off¶

Pick how much to trust the agent:

• Narrow: add allow rules for specific commands, so only those stop asking.

smelt.permissions.extend({
  default = {
    patterns = {
      bash = { allow = { "git status *", "git diff *", "git log *" } },
    },
  },
})

• Broad: switch to Yolo mode (Shift+Tab or --mode yolo).
• Unattended: run headless in scripts and CI, where nothing can ask and anything that would ask is denied unless a rule allows it.

Permissions guard against mistakes, not against a hostile agent. For untrusted prompts, models or MCP servers, run smelt in a container or VM.

Change course mid-task¶

You don't have to wait for a response to finish. Keep typing:

• Enter while busy queues your message for after the turn.
• Ctrl+Enter or Ctrl+Q steers the response in progress.
• Enter on an empty prompt promotes the next queued message to steering; a second empty Enter interrupts and starts that message as a fresh turn.
• Esc pulls queued messages back into the prompt so you can edit them.
• Esc Esc cancels active work or, when idle, rewinds to an earlier turn (/rewind does the same).

In vim visual mode, these act on the selection only. Messages queued during compaction run after it finishes.

Selecting a line in visual mode and pressing Enter sends just that line:

Keep a long task going¶

Goals and auto-continue¶

A goal is a persistent objective that smelt keeps working on across turns, with a progress label in the goal bar. Create one only when you want smelt to keep going on a defined task:

/goal implement the approved migration and validate every package

Goal controls take effect immediately, even while the agent is working, and don't interrupt the current turn. For example, /goal auto off lets the current turn finish and stops further continuation. Creating a goal while the agent is busy is queued like any message, and you can ask the agent to clear one.

Auto-continue runs only while idle, and your queued messages always go first. Set it with smelt.settings.auto_continue: "goal" (default) continues active goals, "off" never continues, and "always" continues any idle session.

If a provider reports a quota or rate-limit error, smelt pauses and queues anything you type. When the provider gives a reset time and auto-continue allows it, smelt retries on its own and shows quota exceeded · resuming at 14:30. Press Enter on an empty prompt to retry now, or Esc Esc to stop the retry (queued messages are kept).

Long-running commands¶

A long bash call can keep running as a supervised background job. Press Ctrl+G while it is in the foreground to stop following it, then use /ps to see its output or stop it. The built-in tool rejects a trailing & so that smelt keeps control of the whole process tree.

Get notified when a turn ends¶

/notify sends a desktop notification when the next turn finishes. Use /notify on or off for the session, /notify clear to return to your default, and /notify status to check. To make it the default:

smelt.settings.notifications = {
  turn_end = true,
}

Delivery depends on your terminal and operating system.

Pick up where you left off¶

Every conversation is saved after each turn, so you can leave and return days later without re-explaining the codebase.

smelt --resume              # open the session picker
smelt --resume <SESSION_ID> # resume a specific session

Inside smelt, /resume does the same. Use /diff afterwards to review what the last session changed.

Other session tools:

• /fork branches the conversation into a new session, so you can try a different approach without losing the first.
• /rewind (or Esc Esc when idle) rolls back to an earlier turn.
• /session shows the id, paths, worktree, model, context usage, costs and compactions. Press c to copy the id or y to copy everything.
• smelt --ephemeral starts a throwaway session that is deleted on exit and never appears in resume lists.

To browse saved sessions and provider requests in a local web UI, run smelt inspect. For health checks, backups and cleanup, see Session maintenance.

Long conversations¶

smelt compacts automatically. When a request would use more than 80% of the model's context window, it summarizes older messages and keeps recent turns. The transcript stays intact, and the prompt bar shows how full the window is (a ? means the number is from another model and refreshes after the next response).

Use /compact only for manual control, such as choosing what the summary keeps:

/compact keep details about the auth refactor

Press Esc Esc to cancel it. Tune the automatic behavior with the auto_compact, compact_threshold and compact_keep_recent_groups settings.

To make a session faster or cheaper:

• Reasoning effort: Ctrl+T cycles off to max. Lower is faster and cheaper; higher suits hard problems.
• Fast mode: /fast requests accelerated inference when the model supports it.
• Helper model: run titles and compaction on a cheaper helper model.

Work on many tasks in parallel¶

Managed worktrees give each task its own checkout without moving your original one. Start in one:

smelt --worktree docs-audit

Or create, pick and enter them from a running session:

/worktree                         # picker and status
/worktree docs-audit --base main # create or enter
/wt docs-audit -b main           # short form

Names are normalized and deduplicated. Worktrees live in <repo>/.worktrees/ by default; change that with smelt.settings.worktree_root. Entering one switches smelt's working directory and reloads project instructions, skills, trusted .smelt/ config and workspace permissions for the new checkout.

An agent in a managed worktree does not push, open a pull request, merge into the base checkout, or remove the worktree unless you explicitly ask. If you ask it to land changes without choosing a strategy, the default is commit, rebase onto the base branch, validate, and fast-forward the base checkout without a merge commit.

Run a quick command without the agent¶

Prefix a line with ! to run a shell command yourself: !git status. The output appears in the conversation, which is useful for a quick check without paying for a full tool call in the agent's context.

Type faster¶

The prompt grows with your input and the whole layout reflows when the terminal is resized:

• Ctrl+J or Shift+Enter inserts a newline.
• Ctrl+R fuzzy-searches your input history.
• Ctrl+X Ctrl+E opens your external editor ($VISUAL, then $EDITOR).
• Ctrl+C clears the input, cancels the agent, or quits, depending on context.
• Enter submits; on an empty prompt it continues the turn when there is history.
• F1 opens help; F3 and F12 toggle the debug and performance panels.
• Stash a draft: Ctrl+S saves your input and gives you a blank prompt, and Ctrl+S again restores it. Handy for a quick side question mid-prompt.
• Predictions: after each turn the agent may suggest your next message as dim ghost text. Tab accepts it and typing dismisses it. Turn it off with smelt.settings.show_prediction = false.
• Vim mode: smelt.settings.vim = true gives insert, normal and visual modes in the prompt and transcript. See Keybindings.

Search the conversation¶

Focus the transcript with Ctrl+W then k, press / to search forward (? for backward) and Enter to jump to the first match. n and N move between matches, Ctrl+C returns to the prompt, and /nohl clears the highlights.

Copy a conversation¶

/copy copies the latest message to the clipboard. Pass a count, a role filter or headers for more:

/copy --role assistant 2
/copy --headers 1

/yank is an alias. This copies conversation messages; copying selected text in the prompt and the kill ring are in Keybindings.