Skip to main content
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 for details.

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

​
Scoped instructions

Mux supports scoped instructions that activate only in specific contexts. You define them using special headings:
DirectiveWhere it worksEffect
Model: <regex>Mux-dedicated files onlyActive for specific models
Mode: <mode>Mux-dedicated files onlyActive for specific modes or agents
Tool: <name>All instruction sourcesAppended 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.
Agent: scoped sections have been removed. Use custom agent definitions instead to customize behavior per agent. Mode: sections are available, but only in Mux-dedicated files (see Mode Prompts below).

​
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.
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).
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): 
## 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): 
## 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: 
## 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)