Skip to content
Ultracite
Esc
↑↓navigate↵open⌘Jpreview

Xum reads AGENTS.md first, CLAUDE.md as backup

Xum picks up AGENTS.md at each workspace location, ahead of AGENT.md or CLAUDE.md, and layers .xum/AGENTS.md on top. Ultracite doesn’t configure Xum’s experimental tool hooks, so the agent runs ultracite fix with its bash tool when the rules tell it to.

Xum by CoderChecked against Xum 0.31.0

# Ultracite Code Standards

This project uses **Ultracite**, a zero-config preset that enforces strict code quality standards through automated formatting and linting.

## Quick Reference

- **Format code**: `npx ultracite fix`
- **Check for issues**: `npx ultracite check`
- **Diagnose setup**: `npx ultracite doctor`

Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.

…
Ultracite’s rules
Where Xum looks for instructions
  1. 1~/.claude/CLAUDE.mdRead only with the Claude compatibility experiment on, at the lowest precedence.
  2. 2~/.xum/AGENTS.mdYour global defaults, layered over the Claude file.
  3. 3AGENTS.mdUltraciteThe workspace root’s shared file: the first of AGENTS.md, AGENT.md or CLAUDE.md, plus AGENTS.local.md.
  4. 4.xum/AGENTS.mdXum-only instructions, loaded alongside the shared file. The place for Model: and Mode: sections.
  5. 5Sub-projectsIn multi-project workspaces, each sub-project and repo directory adds its own shared file and .xum/AGENTS.md.

How Xum reads the rules

At each location, Xum loads the first of AGENTS.md, AGENT.md and CLAUDE.md, appends AGENTS.local.md from the same folder, and adds a Xum-only .xum/AGENTS.md. Locations layer from most general to most specific.

First match
With an AGENTS.md in a folder, Xum skips that folder’s AGENT.md and CLAUDE.md.
Local notes
AGENTS.local.md is appended to the shared file in the same folder. Keep it gitignored for personal tweaks.
Tool sections
A ## Tool: <name> section in any instructions file is appended to that tool’s description instead of the general instructions.
Xum-only sections
Model: and Mode: sections work only in .xum/AGENTS.md, ~/.xum/AGENTS.md and agent definitions.
Comments
Xum strips HTML comments from instruction files before the model sees them.
Legacy names
.mux/ still works as a read fallback for .xum/, and mux as an alias for the xum command.

Put the reminder on the edit tool

Xum runs ultracite fix when AGENTS.md tells it to. Its experimental .xum/tool_post hook runs after every tool in trusted projects, within 10 seconds, but Ultracite doesn’t configure it. A Tool: section is a documented way to put the reminder on the edit tool itself: Xum appends it to that tool’s description.

## Tool: file_edit_replace_string

- Run `npx ultracite fix` on the file after editing it
  1. 01The agent edits a file with file_edit_replace_string or file_edit_insert.
  2. 02AGENTS.md, and any Tool: section on that tool, tell it to run npx ultracite fix.
  3. 03It runs the command with bash in the workspace’s runtime: local, worktree, SSH or Docker.
  4. 04It reads the output and fixes what’s left before moving on.

Worth knowing about Xum

  • Every workspace needs its own install

    A worktree workspace is a separate git worktree, so it starts without your gitignored files, node_modules included. An executable .xum/init runs once when each workspace is created, which makes it the place to install dependencies before the agent runs ultracite.

  • Hooks run only in trusted projects

    Trust gates Xum’s repo-controlled automation: project hooks, workflows and .mux configuration. Grant it in Settings → Security or with xum trust, which records it for the main repository even when you run it from a workspace’s worktree.

  • One-off tasks with xum run

    xum run executes one task and exits, in the current directory or, with --runtime worktree, in an isolated worktree. --budget is a hard spending limit in US dollars, which helps in CI.

  • The Ultracite skill

    Xum discovers skills in .xum/skills/ and .agents/skills/ from the working directory up to the checkout root, so it finds the Ultracite skill init installs in .agents/skills/. Run it with /ultracite.

Xum questions, answered

Does Xum read AGENTS.md or CLAUDE.md?
Either, but not both from one folder: at each location Xum loads the first of AGENTS.md, AGENT.md and CLAUDE.md. With Ultracite’s AGENTS.md in place, a CLAUDE.md beside it isn’t loaded.
Does Xum support hooks?
Yes, as an experiment: executable .xum/tool_pre, .xum/tool_post and .xum/tool_env files in the project or ~/.xum/. tool_post runs after every tool, must finish within 10 seconds, and its output reaches the agent. Ultracite doesn’t configure them.
Xum used to be Mux. Does my setup still work?
Yes. Xum reads .mux/ when .xum/ is missing, keeps MUX_* environment variables working, and still answers to the mux command.
How do I keep personal notes out of the shared rules?
Put them in AGENTS.local.md next to AGENTS.md, and keep it out of git. Xum appends it to the shared file from the same folder.
Why don’t my Model: sections work in AGENTS.md?
Xum no longer parses Model: and Mode: sections in shared files like AGENTS.md; they reach the agent as ordinary markdown. Move them to .xum/AGENTS.md or ~/.xum/AGENTS.md.

Sources

Keep going

Ship less slop

One command sets up your linter, formatter, editor and agents. Works with Oxlint, Biome and ESLint.