Quick start

Installation

Install Mode Agent with a single command.

Quick install

curl -fsSL https://gotmode.sh | sh

Verify

mode --version
0.0.1

Up next, Authenticate.

Authenticate

Mode Agent authenticates you the first time you run it.

mode

The first time you run mode, it opens your browser for magic link authentication. Once you confirm, the CLI is authenticated and ready to use. You won't need to authenticate again on this machine.

Up next, First session.

First session

Start Mode Agent and describe your first task.

Type mode to enter an interactive session.

mode

Once inside the session, describe what you want to accomplish. The Agent reads your goal, deploys the right agents, and they execute in parallel.

The Agent will do the following.

1. Decompose your goal into tasks
2. Assign each task to a specialized agent
3. Execute agents in parallel
4. Deliver tested, ready-to-ship results

What happens under the hood

The planner agent reads your goal, decides which agent roles are needed, and coordinates execution. For a "Build a REST API" task, it might spawn the following agents.

• architect designs the system structure
• coder:1 implements the API routes
• coder:2 implements authentication
• tester writes tests as code is produced

All running simultaneously, communicating through signals.

Agents

Mode Agent spawns specialized agents for each role in your workflow. Each agent has a specific job, an auto-routed model, and runs inside a sandboxed environment.

Built-in agent roles

It ships with agent roles across every business domain. The orchestrator auto-routes each agent to the optimal model based on task type, cost, and latency.

Engineering

Product

Design

Marketing & Sales

Research

Operations

Mode Agent auto-routes each agent to the optimal model. No configuration needed.

Orchestration

The planner agent coordinates all other agents through a shared signal bus.

Execution model

1. You describe your goal and Mode Agent deploys agents
2. The planner decomposes it into tasks and assigns them to agents
3. Agents execute in parallel, emitting signals as they work
4. The reviewer validates diffs and ships tested results

Parallel execution

Unlike sequential AI tools, the Agent runs multiple agents simultaneously. The planner identifies independent tasks and launches them in parallel, only serializing when there are true dependencies.

Model routing

Each agent is automatically routed to the optimal model based on several factors.

• Task type means code tasks route to code-optimized models
• Cost means simple tasks use cheaper models
• Latency means time-sensitive tasks route to faster models

Model routing is fully automatic. No configuration needed.

Signals

Agents communicate by emitting and subscribing to typed signals, not by calling each other directly.

How signals work

Every agent action produces a signal on the shared bus. Other agents can subscribe to specific signal types to coordinate their work.

[coder:1] emit file.created  src/auth/middleware.ts
[tester]  recv file.created  → generating tests for middleware.ts
[reviewer] recv file.created → queued for review

Signal types

View signals in real-time with mode logs --follow.

Permissions

Mode Agent runs every agent in a sandboxed environment. You define the boundaries once in your config and agents operate freely within them. No permission prompts, no interruptions.

{
  "permissions": {
    "fs": {
      "roots": ["./src", "./test"],
      "deny": [".env", "secrets/**"]
    },
    "bash": {
      "allow": ["git", "npm", "make"]
    }
  }
}

File system sandbox

fs.roots defines the directories that make up the sandbox. Agents can read and write freely inside these roots. Everything else is invisible.

fs.deny carves out exclusions within the sandbox for secrets, credentials, and sensitive config.

Command sandbox

bash.allow defines which shell commands agents can execute inside the sandbox. Pipes and subshells that would reach outside the sandbox are blocked automatically.

See Configuration: Permissions for the full reference.

mode

Start Mode Agent. Authenticates automatically on first run.

mode

Starts an interactive Mode Agent session. If this is your first time, it opens your browser for magic link authentication. Once authenticated, you're taken straight into the session.

mode logs

Stream or replay agent signals from a run.

mode logs [run-id]          # Replay signals for a run
mode logs --follow           # Stream live signals from current run
mode logs --agent coder:1    # Filter to one agent

mode stop

Stop a running agent or an entire run.

mode stop                    # Stop all agents in current run
mode stop --agent coder:2    # Stop a specific agent
mode stop --run abc123       # Stop a specific run by ID

Config file

Place .mode/config.json in your project root. Mode Agent reads this file automatically on every session.

{
  "permissions": {
    "fs":   { "roots": ["./src", "./test"] },
    "bash": { "allow": ["git", "npm", "make"] }
  },
  "tmux": { "enabled": true, "layout": "tiled" }
}

The Agent auto-routes all models. The config file is for permissions and display preferences only.

Permissions config

Full reference for the sandbox configuration block. Define the boundaries once and agents operate freely within them.

REST API

The Mode Agent REST API will let you start runs, stream signals, and manage agents programmatically.

Base URL

The base URL will be published here when the API goes live. There is no live endpoint to call yet.

Planned endpoints

See Authentication to get started.

Authentication

How API requests will authenticate once the REST API is live.

Requests will pass your API key in the Authorization header, in this form.

Authorization: Bearer sk_mode_xxxxxxxxxxxx

API keys will be generated from your dashboard, scoped with specific permissions and rate limits.

Runs

How you will create and manage multi-agent runs via the API.

POST /v1/runs

Will start a new agent run from a goal and an optional set of agent roles.

GET /v1/runs/:id

Will return the status and results of a run.

Agents

How you will list and inspect available agent roles.

GET /v1/agents

Will return all available agent roles and their default models.

Planned response

{
  "agents": [
    { "role": "planner", "model": "auto", "parallelizable": false },
    { "role": "coder", "model": "auto", "parallelizable": true },
    { "role": "tester", "model": "auto", "parallelizable": true }
  ]
}