> ## Documentation Index
> Fetch the complete documentation index at: https://mux.coder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instruction Files

> Configure agent behavior with AGENTS.md files

<Warning>
  **Breaking change (`Model:` scoped sections):** `Model:` directives are no longer parsed from
  shared `AGENTS.md`/`AGENT.md`/`CLAUDE.md` files — those headings now appear as ordinary markdown
  to the agent. Move any `## Model: ...` sections into `.mux/AGENTS.md` (or `~/.mux/AGENTS.md`). See
  [Model Prompts](#model-prompts) for details.
</Warning>

## Overview

Mux layers instructions from multiple locations. At each location, Mux loads instructions from two
kinds of files:

**Shared instruction files** — also read by other tools (Cursor, Claude Code, etc.):

1. `AGENTS.md`
2. `AGENT.md`
3. `CLAUDE.md`

Mux picks the first match. If found, it also appends `AGENTS.local.md` from the same directory
(when present).

**Mux-dedicated instruction files** — loaded alongside the shared file:

* `<dir>/.mux/AGENTS.md` (+ optional `<dir>/.mux/AGENTS.local.md`)

Only the exact name `AGENTS.md` is supported inside `.mux/` — no `AGENT.md` or `CLAUDE.md`
fallback. A directory may have only `.mux/AGENTS.md` and no shared file.

### Instruction locations

Instructions are collected from (most general to most specific):

1. `~/.mux/AGENTS.md` — global defaults (Mux-dedicated by construction)
2. Workspace root — shared file + `<workspace>/.mux/AGENTS.md`
3. Sub-project and each repo directory in multi-project workspaces — shared file + `.mux/AGENTS.md`

<Info>
  Mux strips HTML-style markdown comments (`<!-- ... -->`) from instruction files before sending them
  to the model. Use these comments for editor-only metadata—they will not reach the agent.
</Info>

## Scoped instructions

Mux supports **scoped instructions** that activate only in specific contexts. You define them using
special headings:

| Directive        | Where it works           | Effect                              |
| ---------------- | ------------------------ | ----------------------------------- |
| `Model: <regex>` | Mux-dedicated files only | Active for specific models          |
| `Mode: <mode>`   | Mux-dedicated files only | Active for specific modes or agents |
| `Tool: <name>`   | All instruction sources  | Appended to a tool's description    |

**Mux-dedicated sources** (checked in this priority order):

1. Agent definition body (`.mux/agents/<name>.md`)
2. Workspace/project `.mux/AGENTS.md` files
3. Global `~/.mux/AGENTS.md`

`Tool:` sections are honored in all of the above, plus in shared `AGENTS.md`/`AGENT.md`/`CLAUDE.md`
files.

<Note>
  `Agent:` scoped sections have been removed. Use [custom agent definitions](/agents) instead to
  customize behavior per agent. `Mode:` sections are available, but only in Mux-dedicated files (see
  [Mode Prompts](#mode-prompts) below).
</Note>

### General Rules

* **Precedence**: Scoped directives are checked in this order: agent definition →
  workspace `.mux/AGENTS.md` → global `~/.mux/AGENTS.md`.
* **Concatenation**: For `Model:` and `Mode:` sections, **all** matching sections across
  Mux-dedicated sources are concatenated and injected — it is not "first match wins."
* **Isolation**: Scoped sections are **stripped** from the general `<custom-instructions>` block.
  Their content is injected only where it belongs (e.g., into a specific tool's description or a
  special XML tag). `Model:` and `Mode:` sections in shared files are *not* stripped — they remain
  as ordinary markdown in `<custom-instructions>`.
* **Boundaries**: A section's content includes everything until the next heading of the same or
  higher level.

***

### Model Prompts

Scope instructions to specific models or families using regex matching. The matched content is
injected via a `<model-...>` tag.

<Warning>
  `Model:` sections in shared `AGENTS.md`/`AGENT.md`/`CLAUDE.md` files are **no longer parsed**.
  Move `## Model: ...` sections to `.mux/AGENTS.md` (or `~/.mux/AGENTS.md`).
</Warning>

`Model:` is honored only in Mux-dedicated sources: agent definitions, `.mux/AGENTS.md` files, and
`~/.mux/AGENTS.md`.

**Syntax**: `Model: <regex>`

* Regexes are case-insensitive by default.
* Use `/pattern/flags` for custom flags (e.g., `/openai:.*codex/i`).
* Matching sections from multiple sources are **concatenated** (not first-match-wins).

**Example** (in `.mux/AGENTS.md` or `~/.mux/AGENTS.md`):

```markdown theme={null}
## Model: sonnet

Be terse and to the point.

## Model: openai:.\*codex

Keep the todo list current every few minutes while a task is in flight.
```

### Mode Prompts

Scope instructions to a specific mode or custom agent. The matched content is injected via a
`<mode-...>` tag.

`Mode:` is honored only in Mux-dedicated sources: agent definitions, `.mux/AGENTS.md` files, and
`~/.mux/AGENTS.md`.

**Syntax**: `Mode: <mode>`

* `<mode>` is matched exactly (case-insensitive) against the effective mode (`plan` or `exec`) and
  the active agent id (e.g. a custom agent name). A custom plan-like agent therefore picks up both
  `Mode: plan` and `Mode: <its-name>` sections.
* Matching sections from multiple sources are **concatenated** (not first-match-wins).

**Example** (in `.mux/AGENTS.md`):

```markdown theme={null}
## Mode: plan

Always propose a plan before making any changes.

## Mode: exec

Keep the todo list updated throughout the task.
```

### Tool Prompts

Customize how the AI uses specific tools by appending instructions to their descriptions.

`Tool:` is honored in all instruction sources: shared `AGENTS.md`/`AGENT.md`/`CLAUDE.md`,
`.mux/AGENTS.md`, and agent definitions.

**Syntax**: `Tool: <tool_name>`

* Tool names must match exactly (case-insensitive).
* Only tools available for the active model are augmented.

**Example**:

```markdown theme={null}
## Tool: bash

- Use `rg` instead of `grep` for file searching

## Tool: file_edit_replace_string

- Run `prettier --write` after editing files

## Tool: todo_write

- Keep the TODO list current during multi-step work; sidebar progress is derived from it.
```

**Common tools** (varies by model/provider): `bash`, `file_read`, `file_edit_replace_string`,
`file_edit_insert`, `propose_plan`, `ask_user_question`, `todo_write`, `todo_read`, `web_fetch`,
`web_search`.

## Practical layout

```
~/.mux/
  AGENTS.md          # Global instructions (Mux-dedicated)
  AGENTS.local.md    # Personal tweaks (gitignored)

my-project/
  AGENTS.md          # Shared project instructions (read by all tools)
  AGENTS.local.md    # Personal tweaks (gitignored)
  .mux/
    AGENTS.md        # Mux-only instructions (Model:/Mode: directives go here)
    AGENTS.local.md  # Personal Mux-only tweaks (gitignored)
```