How Mind works
One unified agent harness powers every Mind surface. Learn how it connects the IDE, CLI and Web, and why your setup travels with you.
Mind Code is one agent, available everywhere you work. Close your laptop and your session keeps running in the cloud. Check on it from your phone. Pick it up in the IDE the next morning. The IDE, CLI and Web apps are different ways to talk to the same unified agent harness, so when you configure a steering rule, write a custom agent, or connect an MCP server, you're configuring Mind Code itself, not one particular app.
That one idea organises everything else: capabilities live at the Mind Code level and are documented once in Features, while each surface section covers only what that surface adds on top.
One harness, many surfaces
At the centre is the unified agent harness, which handles everything an agent run involves: orchestrating the conversation, executing tools, managing context, evaluating permissions, and talking to the LLM providers. Every Mind surface — the IDE, CLI and Web — is a front end to that same harness.
Standalone process running on host or cloud sandbox
The harness is a standalone process, not a library compiled into each app. It runs alongside your codebase, owns everything on the agent side, and the client owns how you interact with it. Because it's a separate process, the same harness can start on your laptop or inside a cloud sandbox, and it behaves identically in both.
Because the harness is shared, a capability behaves the same wherever it's available. A permission rule denies the same operations in the CLI as in the IDE. A steering file shapes the agent's behaviour identically on every surface. Compaction preserves the same information. The surfaces differ in how you drive the agent, not in what the agent can do.
The boundary is a protocol
Clients talk to the harness through the open Agent Client Protocol (ACP). That includes Mind's own surfaces: the IDE, CLI and Web apps all speak ACP, extended with Mind-specific methods (under the spec's _mind/ namespace) for features like live steering, spec workflows, rich permission prompts, and context usage tracking. Local clients connect over stdio; Web connects to a sandboxed harness over WebSocket. Same binary, same tools, same behaviour on either transport.
Anatomy of a turn
When you send a prompt from any surface, the harness runs the same loop:
- Context is assembled. The harness gathers your prompt, the conversation so far, your steering files, and anything you attached. Prompt Submit hooks run here and can inject context of their own.
- The model plans. The request goes to your selected model, or Auto routes it to the best one for the task, and comes back with text, tool calls, or both.
- Every tool call is checked. Before a tool runs, permission rules are evaluated (deny overrides ask, ask overrides allow), along with mindignore patterns where they're enabled. Pre Tool Use hooks can gate or block the call.
- Tools execute. Built-in tools read and edit files, run shell commands, and search the web. MCP servers and Agent Plugins extend the set, and sub-agents take on delegated work. Post Tool Use hooks react to the results.
- Results feed back. Tool output returns to the model, and the loop repeats until the task is done. Agent Stop hooks fire when the turn completes.
- Context stays managed. As the conversation approaches the model's context limit, compaction summarises older history so the session keeps going.
This loop is why the Features section is organised the way it is: each capability is a stage of the loop, not a bolt-on in one app. A permission rule you write once gates step 3 everywhere. A steering file shapes step 1 everywhere.
What the harness owns
Each harness capability is documented once, at the Mind level:
| Area | What it covers |
|---|---|
| Specs | Structured development workflows: requirements, design, tasks |
| Steering | Persistent project context and conventions |
| Hooks | Event-driven automation around the agent loop |
| MCP | External tool servers, OAuth, tool search |
| Permissions | Capability-based rules for what the agent may do |
| Custom agents | Agent profiles, built-in agents, sub-agent delegation |
| Agent Skills | Portable instruction packages (open standard) |
| Agent Plugins | MCP servers bundled with knowledge, loaded on demand |
| Cloud sessions | Run sessions in a managed cloud sandbox and attach from any surface |
| Context management | Automatic context summarization for long sessions |
| mindignore | Keep files out of agent access with gitignore-style patterns |
| Save and restore | Undo agent changes or fork a conversation at an earlier turn |
| Built-in tools | The agent's file, shell, web, and code tools |
| Router | Auto routing and per-turn model selection |
You'll find these under Features in the sidebar. Not every capability has reached every surface yet, so each page opens with an availability table showing exactly where it works today.
Where the agent runs
The loop is the same everywhere, but the computer it runs on differs by surface:
- IDE and CLI run the harness on your machine by default. Tools operate on your local filesystem, shell commands run in your shell, and builds use your locally installed toolchain and credentials. Both can also create and attach to cloud sessions that run in the same managed sandbox Web uses.
- Web runs the same harness in a managed cloud sandbox. Mind clones your connected repository into an isolated environment, works there, and delivers changes back as pull requests. Nothing executes on your machine, and sessions keep running after you close your laptop.
A cloud session belongs to your account rather than to any one app, so you can start it on one surface and pick it up on another. See Cloud sessions for how each surface creates and attaches to them.
What each surface adds
The surface sections document the experience around the agent: how you invoke it, see its work, and stay in control. Surfaces aren't thin wrappers either: a client can provide its own tools in place of the harness's built-ins where its platform does the job better; the IDE, for example, uses the editor's own APIs for file operations and adds editor-native code analysis on top.
| Surface | What it adds |
|---|---|
| IDE | Editor integration: inline diffs, checkpoints UI, spec panes, dockable chat, and sharing editor diagnostics with the agent through the #Problems context |
| CLI | Terminal-native workflows: the TUI, headless mode for scripts and CI, session management from your shell |
| Web | Zero-setup agent in the browser: sandboxed execution, repository connections, pull-request-based delivery, automations on a schedule |
Your setup travels with you
Configuration follows the same shared model. What you define once applies wherever the harness runs:
| Scope | Location | Travels with |
|---|---|---|
| Project | .mind/ in your repository | The repo. Teammates and every surface that opens it get the same steering, specs, agents, hooks, and MCP servers |
| User | ~/.mind/ on your machine | You. Personal agents, skills, steering, and settings across all local projects |
| Workspace trust | ~/.mind/workspace-roots/<hash>/ | Your machine only. Per-project permission rules stored outside the repo, so a cloned repository can never grant itself trust |
This is why Mind Web can pick up your project's agents and steering with no setup: they read the same .mind/ directory from your repository that the IDE and CLI use locally. See Configuration scopes for the complete reference.
What this means in practice
- Learn once, use everywhere. The
permissions.yamlyou write for the CLI is the same file the IDE consults. A skill you add to your project works from every surface that opens it. - Consistent upgrades. Harness improvements land in one place, and changes that don't touch the client protocol reach every surface with no app updates needed. Global hooks in
~/.mind/hooks/and improved compaction both shipped this way, arriving on all surfaces at once. - Team-wide consistency. Committing
.mind/to your repository gives everyone the same agent behaviour, whether they prefer the IDE, the terminal, or the browser.
Next steps
- Configuration scopes for where every setting lives and how conflicts resolve
- Custom agents to shape the agent's tools, permissions, and prompt
- Permissions to control what the agent can do
- Getting started to install Mind on your surface of choice