Drive the
terminal agent.

Pick a surface.

One code-context engine, four ways to run it. The CLI and MCP server are generally available today; the IDE and the hosted Gateway API are on the way.

Install & log in.

Mesh ships as a single npm package. You need Node.js 20 or newer.

$ npm i -g @trymesh/cli
$ mesh login        # opens your browser to authenticate
$ mesh              # start the interactive agent in your repo

The binary is mesh (aliases mesh-agent and mesh-daemon are installed too). Run it inside any project directory.

Authentication

mesh login opens a browser window against try-mesh.com and stores a session token in ~/.config/mesh/session.json. On a headless box or CI, pass --no-browser (or set MESH_AUTH_NO_BROWSER=1) to log in with email and password in the terminal instead.

First run · /start.

The fastest way to onboard a repo is the /start command. It runs the golden path in one shot: a health check, a full workspace index, a status card, and a short briefing on what it found.

› /start              # doctor + index + status + briefing
› /start reindex      # force a clean re-index
› /start fix          # run diagnostics and auto-fix what it can

Prefer to do it piecemeal? mesh doctor (add fix to apply repairs) runs diagnostics from the shell before you ever open the agent.

Your first change.

Give Mesh a goal. It plans against the indexed context, edits the files it needs, and then verifies — it runs your project's test, typecheck, and/or build scripts and won't report success on a non-zero exit.

› /change add a /healthz route that returns build SHA
  ◇ plan → ✎ edit → ⚡ verify (pnpm test) → ✓ summary
› /undo               # revert the agent's last file change

Everyday verbs live as plain commands: /change to make a focused edit, /fix to resolve the current error, /undo to roll back, /plan to toggle read-only planning. The full set is in the command reference.

The agent loop.

Every task runs the same loop: plan → edit → verify. Mesh assembles context from the index, proposes and applies edits across files, then runs your verification scripts and reads the result. If verification fails, it keeps working; it does not announce "done" without a green run.

• Plan — pulls the relevant files, symbols, and call-graph neighbours into context. Toggle read-only planning with /plan.
• Edit — applies multi-file changes directly to your working tree (honest diffs, no code dumps).
• Verify — runs test / typecheck / build and gates on exit code.

You stay in control of how autonomous that loop is — see approvals & autonomy.

Models & cost-routing.

The default model is google/gemini-3.5-flash. If a call fails, Mesh falls back down a chain — gemini-2.5-pro, then moonshotai/kimi-k2.6 — so a single provider blip doesn't stop the turn.

You don't have to think about this per-prompt. Mesh classifies each task and routes it to the cheapest model that fits:

Override any of it with /model, or pin a model for the session with the MESH_MODEL_ID environment variable. See the full model catalog (12 models) for IDs and pricing.

› /model pick          # interactive picker
› /model list          # show every available model
› /model gemini-2.5-pro save   # switch and persist for next time

The .mesh workspace.

Mesh keeps its per-repo state in a local .mesh/ directory (git-ignored). Nothing in it is required reading, but knowing the layout helps when you debug:

Rename the directory with MESH_DIR, or sweep orphaned files with /mesh gc (dry-run by default).

Index your codebase.

Mesh runs real embedding-based semantic search, not keyword grep. The index combines BM25 lexical scoring, chunk-vector cosine similarity, and call-graph expansion, so a query pulls in the functions that actually relate to it. Embeddings use google/gemini-embedding-001 (768-dim) via the proxy and persist to vectors.bin beside the index.

› /start reindex       # build or rebuild the index
› /debug index         # diagnose or repair a broken index

Indexing is incremental and resumable — it persists a lexical pass first, then layers embeddings on top, and auto-invalidates entries when the underlying file changes. Large repos index in seconds; the agent calls semantic_search under the hood as it works.

Approvals & autonomy.

By default Mesh auto-approves its own write and run tools so the loop flows. Dial that back whenever you want a human gate:

› /config approvals      # toggle auto-approval on/off
› /config steps 40       # cap tool steps for this session

With approvals off, every write or command surfaces a yes/no prompt before it runs. Quality and safety gates are advisory — they inform the agent but never silently block an edit; the one hard backstop is the patch-storm stop, which halts a run that keeps rewriting the same file.

The @trymesh/mcp package (v2.1.8) exposes Mesh's tools over the Model Context Protocol, so other agents — Claude Code, Cursor, Windsurf, VS Code — can call them. Start it with:

$ npx -y @trymesh/mcp

Then register it in your client. For example, in Claude Code's MCP config:

{
  "mcpServers": {
    "mesh": {
      "command": "npx",
      "args": ["-y", "@trymesh/mcp"]
    }
  }
}

Cursor, Windsurf, and the VS Code MCP extension take the same command + args shape in their respective config files.

Resume sessions.

Long sessions get compressed into a capsule — a machine-readable summary of turns, context, cost, and outcomes — so you can stop and pick up later without re-reading everything.

› /compact              # compress the transcript into a session capsule
$ mesh resume          # resume the most recent session
$ mesh --resume <id>   # resume a specific one

Capsules are saved under .mesh/sessions/ and hydrate the transcript on resume. Mesh also auto-compacts as you approach the model's context window, so the loop keeps running on long tasks.

There's a desktop workbench — a React/Electron shell (with a native Tauri build in the tree) wrapped around the same code-context engine. It's real and you can open it, but treat it as a preview: the production assistant-runtime bridge that connects the UI to the live agent loop is still landing. For day-to-day work, the CLI is the supported surface.

Mesh has a speech-to-speech mode you can toggle with /config voice. It's wired but early — handy for hands-free narration of what the agent is doing, not yet a primary interface.

The hosted HTTPS Gateway API exposes the engine over a stable v1 surface, authenticated with the same bearer token the CLI uses. The shape is designed, but the endpoints are not live yet — this section is a blueprint, not a contract. Use the CLI or MCP server today; we'll document the live API here the moment it ships.

The /lab namespace is research-grade and gated behind MESH_EXPERIMENTAL=1. Expect rough edges and breaking changes:

Slash commands.

Twenty top-level commands: eleven plain actions for the everyday loop, plus nine namespaces that group everything else. Old command names are aliased to their new homes, so muscle memory still works.

Model catalog.

Twelve user-selectable models across Google Vertex AI and NVIDIA NIM. Prices are USD per 1,000 tokens (input / output); NVIDIA-hosted models are included through the proxy. Switch with /model <id> or any listed alias.

Configuration.

Settings resolve from three places, most specific wins: a workspace-local .mesh/config.json, your global ~/.config/mesh/settings.json, and any .env in the repo root. The most useful environment variables:

Or run /config setup for a guided wizard.

CLI & flags.

Beyond the interactive TUI, mesh is scriptable. Pass a task as an argument to run it one-shot — handy in CI:

$ mesh "upgrade eslint and fix the new violations"   # one-shot
$ mesh resume                  # resume last session
$ mesh daemon start            # background daemon (status · digest · stop)
$ mesh pr                      # build a PR proof bundle
$ mesh live --verify "pnpm test"  # foreground watcher
$ mesh eval --since 2026-06-01 # replay & score historical turns
$ mesh bench                   # run the benchmark suite

Plus the basics: mesh doctor [fix], mesh login / mesh logout, mesh support, mesh --version, mesh --help.

Troubleshooting.

Login won't open a browser

On headless machines or CI, run mesh login --no-browser (or set MESH_AUTH_NO_BROWSER=1) to authenticate with email and password in the terminal.

A model returns a 4xx / 5xx

Mesh auto-falls-back down its chain, but you can switch immediately with /model gemini-2.5-pro. NVIDIA-hosted models (Qwen especially) are occasionally rate-limited upstream — try a Gemini model if one is unresponsive.

Indexing seems stuck

Run /debug index to diagnose or repair. Indexing is resumable, so re-running picks up where it left off. If embeddings are the bottleneck, you can disable them with MESH_ENABLE_EMBEDDINGS=false (lexical search still works).

Edits didn't seem to land

Check /status and the diff summary — Mesh shows honest diffs and never reverts its own writes. mesh support prints a bug-report bundle if you need to file something.

Changelog.

⟢ This page verified against @trymesh/cli 0.4.104 & @trymesh/mcp 2.1.8 on 2026-06-14.