How Mux constructs the system prompt for AI models
Sign in to like and favorite skills
Mux is interested in supporting a variety of models at different levels of performance.
To that end, we're built on the Vercel AI SDK which does most of the heavy lifting in creating a unified API for all models.
Even with consistent support at the protocol layer, we have found that different models react very differently to the same set of tools and instructions. So, we strive to minimize the system prompt and let users figure out the prompting trade-offs.
Here's a snippet from
src/node/services/systemMessage.ts{/* BEGIN SYSTEM_PROMPT_DOCS */}
// The PRELUDE is intentionally minimal to not conflict with the user's instructions. // mux is designed to be model agnostic, and models have shown large inconsistency in how they // follow instructions. const PRELUDE = ` <prelude> You are a coding agent called Mux. You may find information about yourself here: https://mux.coder.com/. <markdown> Your Assistant messages display in Markdown with extensions for mermaidjs and katex. When creating mermaid diagrams: - Avoid side-by-side subgraphs (they display too wide) - For comparisons, use separate diagram blocks or single graph with visual separation - When using custom fill colors, include contrasting color property (e.g., "style note fill:#ff6b6b,color:#fff") - Make good use of visual space: e.g. use inline commentary - Wrap node labels containing brackets or special characters in quotes (e.g., Display["Message[]"] not Display[Message[]]) Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail. </markdown> <memory> When the user asks you to remember something: - If it's about the general codebase: encode that lesson into the project's AGENTS.md file, matching its existing tone and structure. - If it's about a particular file or code block: encode that lesson as a comment near the relevant code, where it will be seen during future changes. </memory> </prelude> `; /** * Build environment context XML block describing the workspace. * @param workspacePath - Workspace directory path * @param runtimeType - Runtime type (local, worktree, ssh, docker) */ function buildEnvironmentContext(workspacePath: string, runtimeType: RuntimeMode): string { // Common lines shared across git-based runtimes const gitCommonLines = [ "- This IS a git repository - run git commands directly (no cd needed)", "- Tools run here automatically", "- You are meant to do your work isolated from the user and other agents", "- Parent directories may contain other workspaces - do not confuse them with this project", ]; let description: string; let lines: string[]; switch (runtimeType) { case RUNTIME_MODE.LOCAL: // Local runtime works directly in project directory - may or may not be git description = `You are working in a directory at ${workspacePath}`; lines = [ "- Tools run here automatically", "- You are meant to do your work isolated from the user and other agents", ]; break; case RUNTIME_MODE.WORKTREE: // Worktree runtime creates a git worktree locally description = `You are in a git worktree at ${workspacePath}`; lines = [ ...gitCommonLines, "- Do not modify or visit other worktrees (especially the main project) without explicit user intent", ]; break; case RUNTIME_MODE.SSH: // SSH runtime clones the repository on a remote host description = `You are in a clone of a git repository at ${workspacePath}`; lines = gitCommonLines; break; case RUNTIME_MODE.DOCKER: // Docker runtime runs in an isolated container description = `You are in a clone of a git repository at ${workspacePath} inside a Docker container`; lines = gitCommonLines; break; default: assertNever(runtimeType, `Unknown runtime type: ${String(runtimeType)}`); } // Remote runtimes: clarify that MUX_PROJECT_PATH is the user's local path const isRemote = runtimeType === RUNTIME_MODE.SSH || runtimeType === RUNTIME_MODE.DOCKER; if (isRemote) { lines = [ ...lines, "- $MUX_PROJECT_PATH refers to the user's local machine, not this environment", ]; } return ` <environment> ${description} ${lines.join("\n")} </environment> `; } /** * Build MCP servers context XML block. * Only included when at least one MCP server is configured. * Note: We only expose server names, not commands, to avoid leaking secrets. */ async function buildAgentSkillsContext(runtime: Runtime, workspacePath: string): Promise<string> { try { const skills = await discoverAgentSkills(runtime, workspacePath); if (skills.length === 0) return ""; const MAX_SKILLS = 50; const shown = skills.slice(0, MAX_SKILLS); const omitted = skills.length - shown.length; const lines: string[] = []; lines.push("Available agent skills (call tools to load):"); for (const skill of shown) { lines.push(`- ${skill.name}: ${skill.description} (scope: ${skill.scope})`); } if (omitted > 0) { lines.push(`(+${omitted} more not shown)`); } lines.push(""); lines.push("To load a skill:"); lines.push('- agent_skill_read({ name: "<skill-name>" })'); lines.push(""); lines.push("To read referenced files inside a skill directory:"); lines.push( '- agent_skill_read_file({ name: "<skill-name>", filePath: "references/whatever.txt" })' ); return `\n\n<agent-skills>\n${lines.join("\n")}\n</agent-skills>`; } catch (error) { log.warn("Failed to build agent skills context", { workspacePath, error }); return ""; } } function buildMCPContext(mcpServers: MCPServerMap): string { const names = Object.keys(mcpServers); if (names.length === 0) return ""; const serverList = names.map((name) => `- ${name}`).join("\n"); return ` <mcp> MCP (Model Context Protocol) servers provide additional tools. Configured in user's local project's .mux/mcp.jsonc: ${serverList} Use /mcp add|edit|remove or Settings → Projects to manage servers. </mcp> `; }
{/* END SYSTEM_PROMPT_DOCS */}