Skip to main content

​
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).
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:
  • 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.
Agent-specific and mode-specific scoped instructions (Agent: and Mode:) have been removed. Use custom agent definitions instead to customize behavior per agent.

​
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: 
## Model: sonnet

Be terse and to the point.

## Model: openai:.\*codex

Use status reporting tools every few minutes.

​
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: 
## Tool: bash

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

## Tool: file_edit_replace_string

- Run `prettier --write` after editing files

## Tool: status_set

- Set status URL to the Pull Request once opened
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, status_set, 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)