> ## Documentation Index
> Fetch the complete documentation index at: https://mux-advisor-0dak.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Instruction Files

> Configure agent behavior with AGENTS.md files

## Overview

Mux layers instructions from two locations:

1. `~/.mux/AGENTS.md` (+ optional `AGENTS.local.md`) — global defaults
2. `<workspace>/AGENTS.md` (+ optional `AGENTS.local.md`) — workspace-specific context

Within each location, Mux picks the first matching base file:

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

If a base file is found, Mux also appends `AGENTS.local.md` from the same directory (when present).

<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:

* `Model: <regex>` — Active only for specific models (e.g., GPT-4, Claude).
* `Tool: <tool_name>` — Appended to the description of specific tools.

These scoped headings work identically in both:

1. **AGENTS.md files** (global `~/.mux/AGENTS.md` or workspace `<workspace>/AGENTS.md`)
2. **Custom agent definitions** (the Markdown body of `.mux/agents/<name>.md` files)

When searching for a matching section, Mux checks sources in this order: agent definition → workspace AGENTS.md → global AGENTS.md. The first match wins.

<Note>
  Agent-specific and mode-specific scoped instructions (`Agent:` and `Mode:`) have been removed. Use
  [custom agent definitions](/agents) instead to customize behavior per agent.
</Note>

### General Rules

* **Precedence**: Workspace instructions (`<workspace>/AGENTS.md`) are checked first, then global instructions (`~/.mux/AGENTS.md`).
* **First Match Wins**: Only the *first* matching section found is used. Overriding global defaults is as simple as defining the same section in your workspace.
* **Isolation**: These 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).
* **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.

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

* Regexes are case-insensitive by default.
* Use `/pattern/flags` for custom flags (e.g., `/openai:.*codex/i`).

**Example**:

```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.
```

### Tool Prompts

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

**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
  AGENTS.local.md    # Personal tweaks (gitignored)

my-project/
  AGENTS.md          # Project instructions
  AGENTS.local.md    # Personal tweaks (gitignored)
```