Configuration

Files and locations

midas.json                 project settings
midas.jsonc                project settings, with comments
.midas/midas.json          project settings, inside the folder
~/.config/midas/midas.json global settings
~/.config/midas/midas.jsonc global settings, with comments

Midas looks upward from the current directory for a project file, so a session started in a subdirectory still finds the repository settings. A JSONC file may carry comments and trailing commas. Values can reference the environment with {env:VAR} and a file with {file:path}. Run midas debug paths to see every path Midas is using.

Instructions

AGENTS.md is the native instruction file. Midas reads one in the project and one in ~/.config/midas/ that applies everywhere. If a project has no AGENTS.md, Midas will read a CLAUDE.md or CONTEXT.md in its place. If there is no global AGENTS.md, Midas reads ~/.claude/CLAUDE.md.

The instructions key adds more files, globs, or URLs:

{
  "instructions": ["docs/conventions.md", ".cursor/rules/**/*.mdc"]
}

Import explains how to bring CLAUDE.md, Cursor rules, Copilot instructions, and skills into AGENTS.md.

Agents

Midas ships with five visible agents. A primary agent does the work. A subagent is started by another agent for one part of a task.

• buildThe default agent. Full access to the work, subject to permissions.
• planRead-only planning on the strongest tier. It cannot edit files.
• plan-quickThe same planning flow on the cheapest tier.
• exploreA subagent that searches and reads the codebase quickly.
• generalA subagent for research and multi-step work in parallel.

A custom agent is a Markdown file in .midas/agents/ or ~/.config/midas/agents/. The file name is the agent name. The body is the system prompt, and frontmatter sets the description, mode, model, label, and permissions:

---
description: Review migrations for data loss
mode: subagent
model: provider/model
permission:
  edit: deny
---
You review database migrations. Flag any migration that drops a
column, rewrites a table, or cannot be rolled back.

Create one interactively with midas agent create. A custom agent can disable a built-in with disable: true, or merge extra fields into an existing name. Subagent nesting defaults to one level, set by subagent_depth.

Skills

A skill is a folder with a SKILL.md. The frontmatter carries a name and a description. The body is the instruction, and the other files in the folder are available next to it. Midas reads skills from:

.midas/skills/<name>/SKILL.md
~/.config/midas/skills/<name>/SKILL.md
.claude/skills/<name>/SKILL.md
.agents/skills/<name>/SKILL.md

A skill becomes a slash command with its own name. The skills config key adds directories and registries. midas skill push and midas skill pull share one with the team.

Commands

A command is a Markdown file whose body is the prompt. The file name is the command name. Frontmatter can point at an agent, pin a model, and mark the command as a subtask:

---
description: Add a changeset and open the release PR
agent: build
subtask: true
---
Draft the release notes from the commits since the last tag.
Use $ARGUMENTS if the user named a version.

Commands live in .midas/commands/ or ~/.config/midas/commands/. Use $ARGUMENTS for the whole argument string, or $1, $2 for individual words.

MCP servers

A Model Context Protocol server puts another tool inside the session. Add one with the CLI, or write it into the mcp config key:

midas mcp add linear --url https://mcp.linear.app/mcp
midas mcp add local -- npx -y @acme/mcp-server
midas mcp auth linear
midas mcp list

A remote server can carry headers and use OAuth. A local server runs a command, with an optional working directory, environment, and timeout. Its tools and prompts appear in the session. An MCP prompt also becomes a slash command.

Plugins

A plugin extends Midas itself: an auth provider, a hook, a TUI command, or a workspace adapter. Install an npm plugin and add it to config:

midas plugin @acme/midas-plugin
midas plugin ./local-plugin.ts --global

Plugins can also live in .midas/plugins/ as a TypeScript or JavaScript file.

Permissions

Each tool has a permission rule: ask, allow, or deny. By default most work is allowed inside the project. Reading a .env file, leaving the project directory, a repeated failing loop, and clicking or typing in the browser ask first.

• readReading files.
• editCreating, editing, and deleting files.
• bashRunning shell commands.
• external_directoryReading or writing outside the project.
• webfetch, websearchFetching a page and searching the web.
• taskStarting a subagent.
• skillLoading a skill.
• browserOpening a page and interacting with it through the browser tool.
• questionAsking you a question during a run.

Set rules per tool, with a pattern where the tool takes one:

{
  "permission": {
    "edit": "allow",
    "bash": { "git push": "ask", "*": "allow" },
    "read": { "*.env": "ask", "*": "allow" }
  }
}

An explicit deny fails at once. An ask opens a prompt, and choosing allow always writes that rule into your global config. Start a session with --auto to approve everything that is not explicitly denied, or with --manual to be asked for every action.

Memory

Memory is stored locally and recalled into the session when it is relevant. Midas writes a memory when it learns a fact, preference, or decision, and distills notes from finished sessions. You can import a memory export with midas sync --memory. The memory config key controls whether it is on, how much it recalls, and whether finished sessions are distilled into new memory.

Model and defaults

Midas chooses a model per step by default. If you want to pin one, set model or small_model in provider/model form. default_agent picks the agent a new session starts with, and disabled_providers hides providers you do not want.

If another agent runs Midas for you, it should leave the choice of model to Midas. Using Midas from another harness has a rule set to copy into that agent's instructions.

Next steps

• CLI reference lists every command and flag.
• Import covers moving an existing setup into this structure.