--- meta: title: Working with the agent description: "Drive an interactive Muse Code session with slash commands: steer a running turn, manage sessions, control context, set goals and loops, track tasks, and use voice." keywords: slash commands, interactive, steer, queue, interrupt, side chat, compact, recap, export, goal, loop, tasks, voice cms: alias: /model-api/docs/muse-code/interactive target: aidmc --- # Working with the agent The interactive session is where you drive Muse Code. Run `muse` in a project and you get a terminal UI: type a prompt to start a turn, watch the agent work, and steer it with **slash commands**. This page covers the commands and shortcuts you use most. To run one prompt to completion without a UI, see [headless and CI](/docs/muse-code/extending#headless). ## Slash commands {#slash-commands} Type `/` in the composer to open the command palette. Keep typing to filter. Every command on this page is built in — run `/help` to see the full set in your workspace, and `/keymap` for keyboard shortcuts. A command is either **safe to run mid-turn** or **held until the turn ends**. The UI tells you which when a run is active. A few commands are unavailable inside a [side conversation](#side-chats), and say so when you try them. ## Steer a running turn {#steering} You don't have to wait for the agent to finish. While a turn is running: - **`Enter` (steer)**: submit text to *inject into the turn in progress*. The agent applies it on its next step. - **`Alt+Enter` (queue)**: hold your text for the *next* turn instead of the current one. - **`Esc` (interrupt)**: cancel the current turn. `Esc` stops the turn only. It does **not** stop [background terminals](#stop) or subagents. - **`Esc` on an empty composer (retract)**: pull the most recently queued instruction back into the composer to edit or drop it. Repeat to retract older ones. Only the newest eligible item is retractable at a time. `Ctrl+C` also interrupts, but only from an empty composer. With text in the composer, it clears the input instead. > [!NOTE] > If you interrupt a turn while background work is still running, Muse Code sets a reminder to run [`/stop`](#stop). These are two separate actions: `Esc` interrupts the turn, and `/stop` stops background processes. ## Manage the session {#sessions} Each run is an append-only event log (see [how sessions work](#session-model)). These commands start, switch, and branch sessions: ``` /new # start a fresh session, keep the terminal scrollback /clear # start a fresh session and wipe the scrollback /resume # pick a retained session to resume (this workspace) /resume --last # resume the most recent session in this workspace /fork # branch a new session from the current point ``` - **`/new` vs `/clear`**: both begin a new session. The conversation, in-session context, token counts, goal, and tasks all reset. The only difference is your terminal scrollback: `/new` keeps it on screen, and `/clear` clears it. Neither changes on-disk [memory or rules](/docs/muse-code/configuration#local-memory). - **`/resume`**: reopens a retained session and continues it. Resume is scoped to the current workspace and relaunches the session rather than swapping it in place, so expect a brief transition. - **`/fork`**: branches a *new* session from the current session's latest stable point. The source session stays active and unchanged, and the fork doesn't take over your view. Continue the fork later with `muse resume <fork-id>`. ## Side conversations {#side-chats} Start a short parallel conversation without a change to the main thread: ``` /side # open a side conversation /side <prompt> # open one and send the first message /btw <prompt> # alias for /side ``` Muse Code seeds a side conversation from the main session's history, but runs it as its own thread. It snapshots your main transcript and any in-flight run, and sets them aside. Press `Ctrl+C` to return to the main thread. Muse Code restores it exactly, including a run that finished while you were away. You can have one side conversation open at a time. While you're in it, `/side`, `/fork`, `/new`, `/clear`, and `/resume` are unavailable. Return to the main chat first. `/copy` works and copies the side transcript. ## Control the context {#context} These commands manage what the model sees and let you save what it produced: ``` /compact # summarize prior context to reclaim room /recap # show a catch-up summary of recent activity /export transcript # write the on-screen conversation to a .txt /export trajectory # write the full session log to JSON /copy # copy the last response to the clipboard ``` - **`/compact`** replaces earlier model-visible history with an LLM-generated summary to reclaim context room. It's **lossy** for the model's context (summarized, not verbatim), but does **not** clear your on-screen scrollback. Muse Code also compacts automatically when context fills. A manual `/compact` never counts against the auto-compaction budget. Compaction fires the [`PreCompact` and `PostCompact` hooks](/docs/muse-code/extending#hook-events). - **`/recap`** renders a short summary of what happened since the last recap, which is useful after you step away. It needs new activity to summarize, and runs between turns, not during one. A recap is a summary cell only. It doesn't change the model's context. - **`/export`** saves a session two ways: `transcript` writes a human-readable `conversation-<stamp>.txt` of the on-screen conversation, and `trajectory` writes the full session log as JSON (the same document the [`muse export`](/docs/muse-code/extending#headless) CLI produces for the current session). Bare `/export` opens a chooser. Add `--out <path>` to pick a location and `--redacted` to scrub secret-shaped strings. - **`/copy`** copies the markdown of the last completed response to your clipboard. ## Goals and long-running loops {#goals-loops} For work that spans many turns, set a **goal**, and Muse Code holds the agent to it: ``` /goal <objective> # set the session goal /goal # show the current goal /goal edit <objective> # revise it /goal pause # pause goal tracking /goal resume # resume it /goal clear # drop the goal ``` With a goal set, the runtime keeps the agent working toward it. After a turn finishes, the runtime queues a follow-up to continue unfinished work, and it prompts the agent to `report_progress` if the agent goes about 10 model steps without one. The goal reminder also holds the agent to a requirement-by-requirement completion check before it declares the goal done. When you interrupt a turn with `Esc`, Muse Code automatically pauses an unfinished goal, and `/goal resume` restarts it. To run something on a schedule, use **`/loop`**: ``` /loop 10m /run-tests # every 10 minutes, run the /run-tests skill /loop "0 9 * * 1-5" standup # weekdays at 9am (5-field cron) ``` `/loop` schedules a recurring prompt as a cron job. It accepts a shorthand interval (`5m`, `1h`, `2d`) or a full 5-field cron expression (`minute hour day-of-month month day-of-week`, local time). With no cadence, it defaults to every 10 minutes. Muse Code holds a scheduled fire while a run is active, and delivers it when the run ends. Recurring jobs auto-expire after 7 days. A scheduled prompt can be a plain instruction or a `/skill` invocation, and Muse Code passes it through verbatim. > [!NOTE] > There is no dedicated loop-monitor panel. A loop is an ordinary scheduled job the agent manages with its cron tools. Pair it with a `/goal` if you want the runtime to hold progress to a defined outcome. ## Track background tasks {#tasks} When the agent runs work in the background, such as long shell commands or monitors, you manage it through the Tasks surface: ``` /tasks # open the Tasks drawer /task-status # show the selected task's status /task-attach # stream the selected task back into the current run /stop # stop all background terminals and tasks ``` - **`/tasks`** opens a drawer that lists the session's background tasks and terminals, with per-row actions. - **`/task-status`** prints a one-line status snapshot for the selected task. ### `/task-attach` {#task-attach} Re-links a backgrounded task's output into the active run so its records flow into your transcript again. ### `/stop` {#stop} Cancels *all* cancellable background work for the session. This is different from `Esc`, which only ends the current turn. ## When the agent asks you a question {#clarify} Sometimes the agent needs a decision it can't infer from the workspace. It pauses the turn and shows a short set of **clarifying questions**: one to three, each with a few options, single- or multi-select. Pick with the number keys, `Space` toggles a multi-select option, `Tab` adds an optional free-text note, `←/→` moves between questions, and `Enter` submits after a review step. `Esc` interrupts instead of an answer. Your answers are conversational input that steer the next steps. They don't grant the agent any filesystem, shell, network, or approval authority. The agent asks only when the answer changes what it does next. It won't stop to ask about things it can verify itself, or about conventional defaults. To have the agent produce a plan and stop for your approval before it builds, invoke the built-in `/plan` skill (see [skills](/docs/muse-code/extending#skills)). ## Voice input {#voice} Dictate rather than type. Press `Alt+V` (`option-V` on macOS) to start or stop voice input. Muse Code transcribes your speech into the composer, and `Enter` submits it like any other text. ``` /voice status # show voice status /voice debug # toggle voice diagnostics ``` Voice is enabled by default on macOS and off by default on Linux. `/voice` inspects state only. Turn voice on or off in [`/settings`](/docs/muse-code/configuration#settings-file), not with `/voice on`. ## See the agent's reasoning {#reasoning} While the agent works, Muse Code shows a live one-line **reasoning summary** in the status row (on by default). To commit the model's full reasoning into your transcript, turn on `show_reasoning` in [settings](/docs/muse-code/configuration#settings-file). It's off by default and independent of the summary line. [Reasoning effort](/docs/muse-code/configuration#reasoning-effort) governs how much reasoning the model produces (`--reasoning-effort` or `/effort`). ## How sessions work {#session-model} Muse Code records every run as an append-only event log: model calls, tool calls and their results, and approval decisions. Because the session is event-sourced, an interrupted or crashed run replays cleanly on [`/resume`](#sessions). It rebuilds the conversation, closes the interrupted turn, and continues. > [!WARNING] > Treat a resumed destructive step as "verify, then continue." Resume does **not** de-duplicate work that was in flight. Muse Code records a side effect interrupted mid-execution (for example a `write_file` that partially landed) with an **unknown** outcome, and tells the agent to verify the actual state before it retries. The same log powers [`/export trajectory`](#context) and post-hoc inspection with `muse trace inspect`. To run without a persisted log, use `muse exec --no-session-log`. This forfeits resume, export, and reattach (see [headless and CI](/docs/muse-code/extending#headless)). ## Next steps - Set defaults, models, and project context in [configuration and context](/docs/muse-code/configuration). - Understand the guardrails these commands run under in [permissions and safety](/docs/muse-code/permissions). - Distribute work across a team of agents in [extending and automating](/docs/muse-code/extending#multi-agent).