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.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.Inside outer quotes, keep the spaces in the filename as they are.Resolve pending permission or questionnaire requests before sending steer. Use Use
Start from a repository
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:Workspace context
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:Preview pasted images
Starting with 0.4.6, pasting an image withCtrl+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, pressEsc 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 uses, 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.Permissions and execution
Permission mode is independent of Plan Mode: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:/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:Session management
Start, resume, and search
/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
A reusable development loop
1
Establish context
Run
mcode in the repository and read AGENTS.md, relevant implementation, and test entry points.2
Plan the scope
For complex work, use
/plan on and review the proposed scope, risks, and validation.3
Make changes
Add key files with
@, approve tools as needed, and use queue or /steer while the task runs.4
Verify and preserve
Run relevant tests, inspect
/status and /context, then preserve the result with /export or /transcript.