> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimax.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Use MiniMax Code CLI for repository work, multi-turn tasks, plans, permissions, and session recovery.

<div className="code-docs">
  This page covers the most common interactive TUI loop: understand a repository, plan the task, make and verify changes, then continue or recover the session.

  ## Start from a repository

  ```bash theme={null}
  cd /path/to/project
  mcode init .
  mcode
  ```

  `mcode init .` analyzes the directory structure, project rules, relevant implementation, and available scripts, then generates or updates `AGENTS.md`. Start `mcode` afterwards so the agent can use those rules while working.

  A useful first prompt:

  ```text theme={null}
  Read the project rules and relevant tests first. Explain the failure, then fix it and run the smallest relevant test set.
  ```

  Include the expected outcome, change boundaries, and validation method in your prompt. The agent can use file, search, and terminal tools, then summarize changes and verification evidence.

  ## Workspace context

  | Action | Purpose |
  | - | - |
  | `@` | Search for and reference a workspace file or directory |
  | `Ctrl+V` | Paste an image or video file from the clipboard |
  | `/add-dir <path>` | Add a readable and writable workspace directory |
  | `mcode exec --file <path>` | Attach a file to a Headless task |

  Attachments must be accessible from the workspace. A Headless invocation accepts up to 10 files and 100 MB total.

  ### Paste an image file path

  Paste an image file's absolute path into the input to add it as an attachment. Wrap paths containing spaces in quotes. Starting with 0.4.11, macOS and Linux terminals also support escaped spaces in unquoted paths, for example:

  ```text theme={null}
  "/Users/you/Desktop/Screenshot 2026.png"
  /Users/you/Desktop/Screenshot\ 2026.png
  ```

  Inside outer quotes, keep the spaces in the filename as they are.

  ### Preview pasted images

  Starting with 0.4.6, pasting an image with `Ctrl+V` opens a preview above the input with its format, dimensions, file size, and filename. Move the cursor back to the image label in the input to view it again.

  Press `Esc` to dismiss the preview; `Enter` still submits the input. Terminals without image rendering support show the image details, and preview failures do not prevent sending the original image.

  ### Edit messages with images

  Starting with 0.4.8, press `Esc` twice with an empty input, or use `/edit` to edit the previous message. Images return as editable `[Image #1]` labels. You can delete a label, undo the deletion, or resend the image. Move the cursor back to a label to preview it when a readable local file is available.

  The most recent attachment submission in the current process preserves the original label positions. Historical messages without a local editing snapshot recreate labels at the end of the text. Images with an asset ID but no readable local file retain their labels and metadata.

  ### Read elapsed time

  The running status, turn summary, and Goal timer use `s`, `min`, and `h`, such as `30s`, `9min30s`, and `2h9min30s`. Run time covers the current turn, while Goal time accumulates active time, so the values can differ.

  ## Plan Mode

  Use Plan Mode when the task is large, the change scope is uncertain, or you want to review a plan first. Plan Mode controls the planning flow; it does not change tool permissions.

  ```text theme={null}
  /plan on
  ```

  | Command | Purpose |
  | - | - |
  | `/plan on` | Enable Plan Mode |
  | `/plan off` | Disable Plan Mode |
  | `/plan status` | Show the current mode |
  | `/plan view` | Show the latest plan |
  | `Shift+Tab` | Switch modes in the TUI |

  ## Permissions and execution

  Permission mode is independent of Plan Mode:

  | Mode | Use case | Note |
  | - | - | - |
  | Ask | Day-to-day development with explicit approval | Requires an interactive host |
  | Auto | Routine work with risk-based prompts | Higher-risk actions may still ask |
  | Full access | An isolated workspace whose risks you understand | Skips normal confirmation |
  | Off | A controlled automation environment | Confirm the execution boundary first |

  In the TUI, use `/permission ask`, `/permission auto`, `/permission full`, or `Alt+M`. In Headless mode, use `--permission smart|full|off`; `smart` corresponds to TUI Auto. Headless does not support `ask`.

  ## Queue and steer

  While a task runs, `Enter` steers the current Turn. Use `Alt+Enter` to queue a follow-up for after the current response. You can also steer explicitly:

  ```text theme={null}
  /steer Fix the type errors first, then run the full test suite.
  ```

  Resolve pending permission or questionnaire requests before sending steer. Use `/queue` to inspect and manage waiting messages.

  ## Goals

  Goals keep one objective active across multiple turns, which is useful for migrations, refactors, and multi-step verification:

  ```text theme={null}
  /goal Complete the API migration and run the relevant tests
  /goal budget=50K
  /goal pause
  /goal resume
  ```

  | Command | Purpose |
  | - | - |
  | `/goal <objective>` | Create or update a goal |
  | `/goal budget=50K` | Set or change the token budget |
  | `/goal budget=clear` | Remove the budget cap |
  | `/goal edit` | Edit the objective |
  | `/goal pause` | Pause automatic continuation |
  | `/goal resume` | Resume a paused or blocked goal |
  | `/goal clear` | Remove the current goal |

  ## Session management

  ### Start, resume, and search

  ```bash theme={null}
  mcode --continue
  mcode --session
  mcode --session <session-id>
  ```

  Use `/sessions [query]` in the TUI to search and manage sessions. The startup options `--session`, `--continue`, and the compatibility alias `--resume` cannot be combined.

  ### Long conversations and branches

  | Command | Purpose |
  | - | - |
  | `/new` (alias `/clear`) | Create a new session |
  | `/fork` | Fork the current session |
  | `/rewind` | Rewind the current session |
  | `/edit` | Edit the current session |
  | `/retry` | Retry the last message after a failure |
  | `/rename [title]` | Rename a session |
  | `/compact [instructions]` | Compact a long context |
  | `/export [path.md]` | Export a session |
  | `/transcript` | Browse and search the full conversation |
  | `/copy` | Copy the last response as Markdown |

  ## A reusable development loop

  <Steps>
    <Step title="Establish context">
      Run `mcode` in the repository and read `AGENTS.md`, relevant implementation, and test entry points.
    </Step>

    <Step title="Plan the scope">
      For complex work, use `/plan on` and review the proposed scope, risks, and validation.
    </Step>

    <Step title="Make changes">
      Add key files with `@`, approve tools as needed, and use queue or `/steer` while the task runs.
    </Step>

    <Step title="Verify and preserve">
      Run relevant tests, inspect `/status` and `/context`, then preserve the result with `/export` or `/transcript`.
    </Step>
  </Steps>
</div>