Using Mesh Code

Once Mesh Code is installed and connected to your API key, everything happens inside a project folder you choose. Shortcuts below use ⌘ on macOS; use Ctrl on Windows and Linux.

​

Open a project

Choose Open Project… from the menu (⌘ + O) and pick a folder. The agent reads and writes inside that folder and runs commands there.

• Several folders can be open at once; one is active. Each has its own chat, plan, and dev servers, and keeps running when you switch to another.
• The file explorer creates, renames, and deletes files (deletes ask first). Click a file to open it beside the chat.
• Type @ in the composer to reference a file, or drag one from the tree onto the message box.
• Images can be pasted, dropped, or attached into the composer.

Describe the outcome you want, for example “add a health endpoint and run the tests”. Enter sends, Shift + Enter adds a line. Typing while the agent works queues your message for the next turn. Stop ends the current turn, including a running command. For multi-step work the agent writes a plan and updates each step’s status as it goes, in the transcript and in the Plan panel.

​

Permission modes

The mode picker sits next to the composer and is always visible: Reading a file and starting a dev server ask in every mode except Bypass. When the agent asks, the approval shows the exact diff or command. Choose Approve, Always allow, or Reject. Always allow approves that tool for the rest of the session, with the Auto safety checks still applied. An approval left unanswered for 15 minutes counts as a rejection.

​

Safety checks

Some actions come back to you as a question even when your mode would approve them, with the reason stated:

• In Accept edits and Auto: file writes outside the project. In Auto, also shell commands that redirect output, or run cp, mv, mkdir and similar, onto an absolute or ~ path outside the project.
• In every mode, including Bypass: file reads and writes under sensitive paths such as ~/.ssh, ~/.aws, /etc, and ~/.mesh-code, or with a key extension such as .pem. Shell commands that match known dangerous patterns, such as rm -r, rm aimed at / or ~, sudo, and curl … | sh.

These checks are a heuristic, not a sandbox. They read the path given to the file tools and the text of the command. Anything they do not recognize runs under your mode: cp ~/.ssh/id_rsa ., a Python one-liner that opens a file, or a script the agent wrote and then runs. In Auto and Bypass, treat every shell command as able to read or delete anything your user account can. On Windows the checks are written for macOS and Linux paths and commands. The file checks don’t cover paths inside ~/.ssh, ~/.aws or ~/.mesh-code, whichever slash you use; only a few key-file extensions are caught. Destructive commands such as del /s, rd /s and Remove-Item -Recurse aren’t caught either. Use Ask every time or Accept edits there if that matters to you.

​

Choose a model

The model control in the composer bar names whatever decides the model. Its popover holds the routing switch and the effort dial.

• Pinned: one model for every prompt. Pick it from the model browser: fuzzy search, context window, and per-1M-token pricing for every model in the live catalog, with filters for free and text-only models.
• Smart (local): a table bundled with the app classifies each prompt and picks a model per turn. It runs on your machine, bills no extra tokens, and shows which model it would pick and why before you send.
• Gateway auto: Mesh API’s Auto Routing picks the model. This costs a classifier hop.

With routing on, the bar reads Smart routing or Auto routing until a step has answered, then shows the model that ran. A ROUTED tag marks it when that model differs from your pinned one. In Settings (⌘ + ,) you can also set:

• Fallback order: if the primary model fails or is rate-limited, the gateway tries these models in order. See Retry & fallback.
• Never use: models the router will never pick.
• Reasoning effort, writing style, token savings, and Max steps per turn (0 means unlimited).

Settings › Model → Refresh fetches the latest models and prices from Mesh API.

​

Cost

The composer bar shows session tokens and cost, updated after each step while the agent works. Each turn also gets a line in the transcript with the model, steps, tokens, cost, and time. Cost is the figure Mesh API billed for each request. When that figure cannot be fetched, the app estimates from the catalog’s per-token rates and marks the number with ~.

​

Panels

The right rail holds the panels. It can be resized or hidden, and the sidebar collapses with ⌘ + B.

​

Command palette and settings

• ⌘ + K opens the palette. Every setting is listed as a runnable action, and you can search by name or by what it does (typing “cheap” finds token savings). Typing / in an empty composer opens it too.
• ⌘ + , opens Settings, grouped by category.
• Theme: light, dark, or follow the system.

​

Sessions and the project journal

• Conversations are saved to disk and restored on launch, with the transcript, plan, and cost totals.
• Each project keeps a list of past conversations you can switch between. Sessions are grouped by day in the sidebar, and a dot marks a running one.
• The project journal is a notebook the agent keeps per project: commands that ran the project, what is built, and learnings. It is added to every new session, so the agent starts out knowing how to run the project. It is stored outside your repo, so it never shows up in git status.
• Sessions, transcripts, and journals live in ~/.mesh-code. See Data and uninstall.

​

Current limits

• One agent turn at a time per session. Messages you type meanwhile queue.
• The Shell panel is a pipe, not a terminal, so full-screen programs such as vim or top do not run.
• On Windows the Shell panel needs a POSIX sh on your PATH (for example the bin folder of Git for Windows), and Ctrl + C does not stop a command. Use your own terminal instead.
• Web search goes through Mesh API’s tools. There is no local browsing.
• A model the gateway prices at zero and leaves out of the catalog shows $0.

Found a rough edge? Send feedback in the sidebar opens a short form. For problems, see Mesh Code troubleshooting.