Set up an AI agent to help with your mizer project

Creates (or updates) a MIZER-AGENTS.md file in your project directory: a short routing card that AI coding agents read automatically on startup. It is not a mizer reference, on purpose - a summary complete enough to work from is a summary an agent will work from instead of reading the skill, and it goes stale a release later. The card carries only what has to be said up front, then where the task skills are, the path to mizer's API index (a curated list of every exported mizer function, grouped by workflow stage) and how to reach your R session. Argument lists are bundled nowhere: those go stale silently, so the card sends agents to the help pages of the mizer version you actually have installed.

Usage

setup_mizer_agent(
  path = ".",
  overwrite = FALSE,
  r_session = TRUE,
  run_r = TRUE,
  pkg_dev = FALSE,
  rprofile = FALSE,
  agents = .agent_choices,
  check_version = TRUE
)

Arguments

path

Directory in which to create or update the agent files. Defaults to the current working directory, which should be your R project root.

overwrite

If TRUE, replace existing AGENTS.md, CLAUDE.md and GEMINI.md files entirely with what a fresh setup would write, discarding your project notes: the block for AGENTS.md and a bare @AGENTS.md import for the other two. If FALSE (the default), keep the rest of each file and only refresh the marked mizer block, adding it at the top if it is not there yet. MIZER-AGENTS.md is always overwritten to ensure it stays up-to-date.

r_session

If TRUE (the default), configure the r-mizer MCP server so that the agent can read mizer's documentation, your global environment and, in RStudio or Positron, the open document. Set to FALSE to write no MCP config at all.

run_r

If TRUE (the default), let the agent evaluate R code in your session, which is what allows it to project or calibrate a model and see the resulting plots. The code runs in your global environment with no sandboxing, so the agent can overwrite your objects; work under version control, or set this to FALSE for a read-only connection. Ignored when r_session = FALSE.

pkg_dev

If TRUE, also expose btw's package development tools (load_all(), document(), test(), check() and test coverage), which run against the package in your session's working directory. Set this when the project is itself an R package, such as a mizer extension. FALSE by default, since these tools do nothing useful in an ordinary modelling project. Ignored when r_session = FALSE.

rprofile

If TRUE, append a guarded btw::btw_mcp_session() call to the project .Rprofile, so that each new session hands itself to the MCP server automatically. FALSE by default, in which case you call connect_mizer_agent() yourself. The .Rprofile calls btw directly rather than going through this package, so that a project still starts cleanly without mizerAgents installed. R reads a project .Rprofile only when it starts in that directory, which RStudio and Positron guarantee for a project and starting R from a shell does not, so from a terminal either start R in the project root or call connect_mizer_agent() yourself. Ignored when r_session = FALSE.

agents

Which agents to configure the server for. By default all of them, since the config files are small, sit in different places and do not interfere with each other, so a project set up on your machine works for a collaborator using a different agent. Any of:

Value	File written
"claude"	.mcp.json
"codex"	.codex/config.toml
"gemini"	.gemini/settings.json
"antigravity"	.agents/mcp_config.json
"cursor"	.cursor/mcp.json
"vscode"	.vscode/mcp.json
"posit"	.posit/assistant/settings.json
"copilot"	(none; snippet printed on request)

"posit" covers Posit Assistant, which runs in RStudio as well as Positron. Copilot CLI reads MCP config only from the user-wide ~/.copilot/mcp-config.json, so nothing is written for it. Pass agents = "copilot" explicitly (on its own or alongside others) and the snippet to paste there is printed; the default, which asks for every agent, leaves it out rather than print a screenful for everyone. Ignored when r_session = FALSE.

check_version

Logical; whether to check GitHub for a newer version of mizerAgents and say so if there is one. Defaults to TRUE. The check is made after everything else is written, times out after two seconds and never fails the setup, but set it to FALSE to keep the call offline.

Value

Invisibly returns the path to the AGENTS.md file.

Details

It also creates (or updates) the instruction files agents read at startup - AGENTS.md, CLAUDE.md and GEMINI.md - so that agents read both the project-specific instructions and the mizer reference. All three are handled, because none of them is a fallback for another: Claude Code reads CLAUDE.md and not AGENTS.md, and Gemini CLI reads GEMINI.md, so an agent that looks only for its own named file still has to find something.

AGENTS.md gets a short note and a @MIZER-AGENTS.md import. Agents that resolve @ imports (Claude Code, Gemini CLI) pick the reference up automatically at startup; the note tells those that do not (Codex, Copilot) to read the file themselves. The block is delimited by <!-- mizerAgents: start --> and <!-- mizerAgents: end --> comments and is refreshed in place on every run, so that improvements to it reach existing projects. Add your own project notes outside those markers, where they will be left untouched.

CLAUDE.md and GEMINI.md are treated differently depending on whether your project already has them:

• If the file is not there, it is created containing the single line @AGENTS.md and nothing else. Your project instructions then have one home, AGENTS.md, rather than three copies to keep in step by hand.

• If the file is already there, it gets its own copy of the block, exactly as AGENTS.md does, and the rest of the file is left alone. No @AGENTS.md import is written into it and none is removed, so which of your own instructions reach which agent is unchanged. If it already imports AGENTS.md, whether you wrote that yourself or an earlier version of this package did, the file is left untouched - the block reaches the agent through the import.

It also installs a set of agent skills (one sub-directory with a SKILL.md per skill, e.g. analyse-and-plot and build-model), giving step-by-step guidance for common mizer workflows. Agents discover these themselves and load one when a task matches, but they look in different places: Claude Code in .claude/skills/, Codex and Gemini CLI in .agents/skills/. So the skills are installed in both, as two identical copies. (Copies rather than links, because links are unreliable on Windows, on network drives and under OneDrive.) Like MIZER-AGENTS.md, the skills are package-managed and refreshed on every call so they stay up to date.

The skills are taken from the installed mizer (inst/skills/), not from this package, so the guidance an agent follows always describes the mizer the project is actually running. In mizer each SKILL.md is also the source of the matching guide-* article on the mizer website, so the two are the same document. Skills arrived in mizer 3.3.0; against an older mizer this function still writes everything else and reports that it installed none.

What a project learns about mizer is kept separate from them, so that neither overwrites the other. Each skill has a NOTES.md, at .claude/skills/<name>/NOTES.md, which this package never writes and which the SKILL.md tells agents to read alongside it and to treat as taking precedence: that is where an agent should record what it discovers about your model. Both copies of a skill name that one file, so that Claude Code and Codex share one set of notes rather than keeping one each. Findings that are true of mizer in general belong upstream instead, and the skills tell agents to offer to report them at https://github.com/sizespectrum/mizerAgents/issues, so that every project gets them in the next release.

Refreshing works file by file rather than by replacing whole directories, so a NOTES.md, or a skill of your own, is left alone. The hashes of the files installed are recorded in a .mizerAgents.json in each of the two directories; a file that has since been edited is recognised, kept, and reported, with the new version written beside it as <file>.new for you to merge, rather than silently overwritten. A skill of another tool's in .agents/skills/ that happens to share a name with one of ours is treated the same way. (A project set up by version 0.3.2 or earlier has no record in .claude/skills/, so the first run after upgrading refreshes the skills there as it always did and starts keeping one.) Files that later versions stop shipping are removed if they are unmodified.

MIZER-AGENTS.md does not list the skills, since every agent set up here already lists the ones it finds. It tells agents to read the matching skill before starting a task, and tells an agent without skill support where to look.

Finally, unless r_session = FALSE, it configures an MCP server named r-mizer so that the agent can reach your live R session. Agents have not converged on where MCP servers are configured, so by default every one that supports a project-level config gets its own file: Claude Code, Codex, Gemini CLI, Antigravity, Cursor, VS Code and Posit Assistant. See the agents argument for the paths and for how to narrow the list. The server is provided by the btw package, which you need to install separately. This gives the agent help pages and vignettes for the mizer version you actually have installed, rather than whatever mizer API it remembers, along with a view of the objects in your global environment, and it can run mizer code there and see the plots that come back. For the server to see your session you must run connect_mizer_agent() in the R console once per session; passing rprofile = TRUE adds the underlying btw::btw_mcp_session() call to the project .Rprofile so that it happens automatically - which needs R to be started in the project directory, as RStudio and Positron do for you and a shell does not. Only the r-mizer entry of .mcp.json is package-managed; other servers you configure there are left alone.

After running this function, start your AI coding agent (e.g. claude, codex, copilot or gemini) from a terminal in the project directory - the RStudio or Positron Terminal pane, or any other terminal - and it will immediately have the mizer context it needs.

Nothing here is tied to a particular editor. The files are read by agents running in a terminal, and the session connection is a socket, so a project set up this way works the same from RStudio, Positron, a bare R console, ESS or the VS Code R extension. The one exception is the agent's ability to read the document you have open, which needs rstudioapi and so works only in RStudio and Positron; everything else does not.

See also

connect_mizer_agent() to hand your session to the server this configures, update_mizer_agent(), which refreshes the files a project already has while keeping the settings it was set up with, and remove_mizer_agent(), which undoes all of this.

Examples

if (FALSE) { # \dontrun{
# Run once in your mizer project to set up AI agent support
setup_mizer_agent()

# In a mizer extension package, add the package development tools and
# connect the session automatically on startup
setup_mizer_agent(pkg_dev = TRUE, rprofile = TRUE)

# A read-only connection: documentation and inspection, but no execution
setup_mizer_agent(run_r = FALSE)
} # }