Mesh in five minutes.

Mesh is a terminal-first code-context platform for AI-assisted software work: repository capsules, verified change workflows, runtime diagnostics, issue automation, and durable workspace memory. The CLI is the canonical product — slash commands and 100+ workspace.* agent tools. MCP exposes a focused subset for external clients; IDE and Gateway API are preview surfaces.

Pick a surface.

Install.

Mesh is shipped as a single npm binary. macOS, Linux, and WSL2 are first-class. Node 20+ required.

# global install (recommended)
$ npm i -g @trymesh/cli

# or with pnpm / yarn
$ pnpm add -g @trymesh/cli
$ yarn global add @trymesh/cli

# verify
$ mesh --version
mesh 0.4.37

Global install is the recommended default. For one-off runs without installing, use npx -y @trymesh/cli. First launch prompts Mesh login for the shared LLM gateway (no AWS/Bedrock credentials required).

First run.

Mesh opens against your current working directory. New users should run the golden path first: doctor, optional safe fixes, index, status, and repo briefing.

$ cd my-project
$ mesh

mesh › /start
▸ running doctor · checking gateway · reading git state
✓ workspace healthy · 247 files indexed
▸ company brain: no durable memory yet
✓ repo briefing ready

mesh › /change fix voided invoices being charged
▸ scoped: invoices.ts, webhooks.ts, billing.spec.ts
✓ patch drafted · verification detected: npm test
  review diff, then promote only after checks pass

What just happened?

1. Brief — /start runs diagnostics, indexes the repo, and gives the agent a grounded project briefing.
2. Scope — /change narrows the edit to likely files before any patch is written.
3. Verify — Risky work flows through timelines, tests, audit logs, and proof artifacts before promotion.

Concepts.

Six things to understand before you go deep.

Slash commands · operator surface.

Mesh slash commands are the operator controls for the CLI: onboarding, verified changes, workspace memory, issue automation, capsules, voice, isolated timelines, runtime diagnostics, visual inspection, model routing, and safety policy.

CLI · overview.

The terminal CLI is the canonical Mesh experience. Everything else (IDE, MCP, API) wraps the same engine.

Commands

Models & keys

The CLI defaults to the Mesh LLM gateway with Gemini 3.5 Flash (google/gemini-3.5-flash). Sign in once with mesh (Supabase session); no AWS or Bedrock setup. Switch models with /model, route NVIDIA NIM models with NVIDIA_API_KEY, or point MESH_ENDPOINT at a custom HTTPS proxy.

# default through the Mesh gateway (after mesh login)
$ mesh
mesh › /model list

# switch inside the shell
mesh › /model qwen3-coder

# optional direct NVIDIA route
export NVIDIA_API_KEY=nvapi-...

# optional custom proxy (legacy alias: BEDROCK_ENDPOINT)
export MESH_ENDPOINT=https://your-llm-proxy.example.com

Run /model list in the shell for the full catalog. Legacy Claude/Bedrock model IDs in old settings are migrated to the Gemini default automatically.

Voice mode

Speak instead of type from inside the interactive CLI. Voice uses local speech-to-text — audio stays on your machine.

$ mesh
mesh › /voice setup   # one-time: local model + mic permissions
mesh › /voice on      # enable voice in this session

✓ voice loop ready
🎙  press [space] to talk · [esc] to cancel
mesh › /doctor voice fix  # repair FFmpeg / model assets if needed

IDE · preview status.

The Mesh IDE is a desktop-first workbench shell: React/Electron UI, Monaco editor, file explorer, terminal SSE, git status/diff/commit APIs, and an assistant/action contract.

Status: the current IDE is not the canonical production agent yet. The assistant bridge to the real Mesh runtime is in progress; use the CLI or MCP server for verified agent work today.

1. Use Mesh CLI as the source of truth for agent execution.
2. Run mesh, /start, and /index in your repository first.
3. Use the IDE preview for workbench exploration, file navigation, terminal, and git surfaces.
4. Watch the runtime bridge milestone before relying on IDE chat for production changes.

First launch on macOS

The IDE is currently distributed unsigned (no Apple Developer Program yet). After downloading Mesh.dmg and dragging Mesh IDE.app into your /Applications folder, macOS may show "Mesh IDE is damaged and can't be opened". That's macOS Gatekeeper rejecting any binary without Apple-issued notarization.

Run this in Terminal once and the warning goes away:

xattr -cr "/Applications/Mesh IDE.app"

The command removes the com.apple.quarantine attribute Chrome/Safari adds to downloaded files. Notarized builds will land once we register with the Apple Developer Program.

Shortcuts

MCP · install & run.

@trymesh/mcp is a stdio MCP server for Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code. It exposes profile-based mesh_* tools (25 built-in tools across profiles; 8 in default core). The full interactive slash-command workflow and 100+ workspace.* tools still live in the terminal CLI.

$ npx -y @trymesh/mcp

▸ stdio MCP server · profile: core (8 tools)
✓ mesh_workspace_status
✓ mesh_search
✓ mesh_read_capsule
✓ mesh_read_targeted
  … review · terminal · memory · full profiles available

MCP now includes timelines/impact/review/memory tools in non-core profiles. Use mesh in the terminal when you need full interactive orchestration (slash workflows, approvals, long-run state, and session-level control).

Manual Claude / Cursor config

Add the server manually in your MCP client config. Point stdio at npx -y @trymesh/mcp and set the workspace path:

{
  "mcpServers": {
    "mesh": {
      "command": "npx",
      "args": ["-y", "@trymesh/mcp"],
      "env": {
        "MESH_WORKSPACE_PATH": "/absolute/path/to/your/project"
      }
    }
  }
}

Cursor and Windsurf use the same stdio command. Claude Code users can keep the generated config and let the installer update it.

MCP tools (core profile)

These are the default mesh_* tools in the core profile. Additional profiles (review, terminal, memory, full) add risk/test, command, memory, and timeline/impact capabilities. The full workspace.* catalog remains CLI-native.

Gateway API · v1 blueprint (coming soon).

The hosted HTTPS Gateway API is coming soon. The shape below is the intended v1 contract so teams can design integrations early. Today, use the CLI as the production path.

Auth, workspaces, and indexing jobs

Planned auth is Bearer-token based, scoped to one or more workspaces. Indexing is asynchronous and returns a job id so large repositories can build in the background.

# auth header required on all /v1 endpoints
Authorization: Bearer msk_live_xxx

# create / register workspace (planned)
POST /v1/workspaces
{
  "name": "mesh-cli",
  "repoUrl": "https://github.com/dreddi-edit/mesh"
}

# start indexing job (planned)
POST /v1/workspaces/{workspaceId}/index
{
  "mode": "incremental", # full | incremental
  "paths": ["apps/cli/src"],
  "force": false
}

# poll job
GET /v1/jobs/{jobId}
status: queued | running | succeeded | failed | cancelled

Index job response shape (planned)

Capsules and context reads (planned)

Capsules remain the core context unit. API reads mirror what CLI workflows consume: compact file context, targeted symbol reads, and handle-based recovery.

POST /v1/workspaces/{workspaceId}/read/capsule
{
  "path": "apps/cli/src/agent-loop.ts",
  "tier": "summary" # summary | detailed
}

POST /v1/workspaces/{workspaceId}/read/targeted
{
  "path": "apps/cli/src/agent-loop.ts",
  "symbol": "getSlashCommands",
  "contextLines": 24
}

# handle-based recovery (planned)
GET /v1/workspaces/{workspaceId}/spans/{spanId}

Current CLI behavior is unchanged: local capsule artifacts are stored under ~/.mesh/. Hosted API storage/retention policy will be published at launch.

Search and recovery (planned)

v1 search is intended to support both intent search and symbol-targeted retrieval. Recovery remains handle-first (spanId, symbolId) for deterministic follow-up reads.

POST /v1/workspaces/{workspaceId}/search
{
  "query": "where is slash command routing implemented?",
  "mode": "hybrid", # lexical | semantic | hybrid
  "limit": 10
}

# optional continuity for multi-step workflows
"cursor": "srch_..."
"filters": { "pathPrefix": "apps/cli/src" }

Errors, limits, and status model (planned)

Responses are intended to use a normalized error envelope with stable machine-readable codes. Rate limits and quotas will be account-tier based once the hosted API is available.

{
  "error": {
    "code": "WORKSPACE_NOT_INDEXED",
    "message": "Workspace has no completed index yet.",
    "requestId": "req_01JY3Z4...",
    "hint": "Start POST /v1/workspaces/{workspaceId}/index and retry."
  }
}

Configuration.

Mesh reads repo-local settings, user settings in ~/.config/mesh/settings.json, and environment variables. Gateway routing uses MESH_ENDPOINT and MESH_MODEL_ID (legacy BEDROCK_* names still work as aliases).

# Mesh LLM gateway (default; login via mesh CLI)
export MESH_ENDPOINT=https://mesh-llm.edgar-baumann.workers.dev
export MESH_MODEL_ID=google/gemini-3.5-flash

# runtime limits (defaults: max_tokens 8000, temperature 0)
export MESH_MAX_TOKENS=8000
export MESH_TEMPERATURE=0

# optional direct NVIDIA NIM models
export NVIDIA_API_KEY=nvapi-...

# opt-in expensive local features
export MESH_ENABLE_EMBEDDINGS=1
export MESH_ENABLE_BACKGROUND_RESOLVER=1

# deterministic CI/local runs
export MESH_DISABLE_WATCHERS=1

# legacy aliases still accepted: BEDROCK_ENDPOINT, BEDROCK_MODEL_ID, …

Telemetry

Mesh ships with telemetry off. On first run you may be asked to opt in; that sets telemetry.contribute in ~/.config/mesh/settings.json. When enabled, we collect anonymous session metadata (command invocations, error types, capsule sizes) — never source code or prompts. Set telemetry.contribute to false any time.

Troubleshooting

Changelog

• CLI 0.4.37 — current release line. Expanded slash-command registry (51 entries), refreshed model catalog, fullscreen TUI path, and ongoing verified-change workflow hardening.
• MCP 2.1.8 — current stdio release. Profile-based mesh_* surfaces (core/review/terminal/memory/full), with core fixed at 8 tools and expanded capabilities in broader profiles.
• CLI + MCP alignment — shared runtime concepts, but different interaction models: CLI for full interactive orchestration, MCP for profile-scoped tool access in external clients.
• IDE preview — React/Electron workbench exists; production assistant runtime bridge is still in progress.
• Gateway API — Not shipped; CLI is the supported integration surface.

Stuck? Join the waitlist for direct support during private preview, or open an issue on GitHub.