Skip to main content
Use Beads with Mux through AGENTS.md, optional layered Mux instruction files, and Mux hooks.
The default setup writes a managed Beads section to root AGENTS.md.

Workspace and Global Layers

Mux also supports workspace and global instruction layers:
Project setup writes .mux/AGENTS.md and installs Mux hook files under .mux/:
  • .mux/init
  • .mux/tool_post
  • .mux/tool_env
Global setup writes the section to ~/.mux/AGENTS.md. Mux loads that file in every workspace, so there the section applies only in repositories that use beads, and a new file holds only the section. The workspace layer’s .mux/AGENTS.md run from your home directory, and the root AGENTS.md run from ~/.mux, are that same file, so setup manages them as the global layer. Run from ~/.mux, setup installs no hooks and, with --project, no workspace layer, since Mux does not load ~/.mux/.mux, and bd setup mux --remove removes the global section.

Remove