User-level configuration¶

ai-rulez generate writes inside the project. ai-rulez generate --user does the same for a person: it renders a user config into the per-user directories each harness reads (~/.claude, ~/.agents/skills, ~/.codex, ~/.gemini, ~/.config/opencode, ~/.copilot, ~/.pi/agent, and so on for every harness that documents one; see Where things go), so personal or role-based instructions and skills follow you across every repository, including ones that do not use ai-rulez.

It is opt-in: nothing is written to the home directory unless you pass --user.

The user config¶

The user config has the same schema as a project config and lives in ~/.config/ai-rulez/ (or $XDG_CONFIG_HOME/ai-rulez, or any directory with --config <dir>):

~/.config/ai-rulez/
  config.toml
  rules/        skills/        agents/        domains/

version = "5.0"
name = "me"
presets = ["claude", "codex", "gemini"]
default = "backend"          # the role of this machine; see below

[profiles]
backend = ["backend"]
frontend = ["frontend"]

presets, profiles, default, builtins, includes, installed_skills, [[hooks]], [permissions] and [claude.settings.managed] work as in a project. The project-only features do nothing at user level: MCP servers, [[scopes]], [plugin]/[marketplace], agents_md, the .local overlay and gitignore management. A preset with no documented user-level location (see the table) is reported with the reason and skipped.

generate --user ignores the project in the working directory entirely. It reads it only to warn when a skill of the same name exists at both levels.

Roles¶

The simplest role is a profile. Keep the shared content at the top level and one domain per role, then choose the role per machine with default in the user config or per run with --profile:

ai-rulez generate --user --profile frontend

Switching the role removes the files of the old one on the next run (they are in the manifest).

For finer control, declare [[roles]] in the user config (domains, per-kind include / exclude selectors, inheritance and a per-skill skill_mode that becomes skillOverrides in ~/.claude/settings.json) and select one with --role, which is mutually exclusive with --profile:

ai-rulez generate --user --role backend-engineer --yes

ai-rulez does not decide who holds a role: an external tool picks the name. See Roles, including Integrating an identity tool or UI.

Commands¶

ai-rulez generate --user --dry-run     # list every path that would be written, merged, skipped or removed
ai-rulez generate --user               # same list, then asks before writing (interactive terminal)
ai-rulez generate --user --yes         # no prompt (required in a non-interactive shell)
ai-rulez clean --user                  # remove exactly what generate --user wrote

--config <dir> selects another user config. --user cannot be combined with --recursive or --plugin. The full write list is printed before the first write, whatever the flags.

Safety¶

• Only documented locations. An output is written only where the preset's declared user-level layout (the table below) places it. Anything else a preset renders (project-only rules folders, MCP files) is dropped and counted; --debug names each one.
• Hand-authored files are never replaced. A file that exists and was not written by ai-rulez (not in the manifest, no generated banner, not byte-identical to the output) is skipped and listed as skip:. A skill directory holding one is skipped whole. ~/.claude/CLAUDE.md you wrote yourself stays yours; ai-rulez writes nothing at that path.
• Shared settings documents are merged, not rewritten. ~/.claude/settings.json, ~/.codex/hooks.json, ~/.cursor/hooks.json and ~/.gemini/settings.json get only the keys ai-rulez owns (hooks, permissions.*, env, skillOverrides from Hooks and permissions); every other key survives generate and clean. The generated-file [guard] is never added: it protects a project, not the home directory.
• No symlink escapes. Every destination, resolved through symlinks, must stay inside the home directory (or the relocated tool home, see below). A ~/.claude symlinked into ~/dotfiles is followed; one pointing out of the home directory stops the run before anything is written. A symlinked file is skipped, except for the settings documents above.
• Clean removes only what was recorded. The manifest is ~/.config/ai-rulez/.generated-manifest.json (plus .generated-manifest.local.json for the keys merged into shared documents). clean --user, and generate --user after you drop content, remove a file only if it is listed there and, for files that carry a generated header, still looks generated. The manifest also records the directories generate --user created below your home directory (~/.cursor, ~/.claude/skills/<id>, ...); clean --user removes those once empty. A directory that existed before ai-rulez ran is never removed, and neither is one that still holds a file of yours. A manifest written by an older version records no directories, so the first generate --user after upgrading starts the record. A relocated tool home is never removed, and the user config is never touched beyond its two manifest files. Keep ~/.config/ai-rulez in your dotfiles repository if you like, but add the two manifest files to its ignore list.
• --dry-run writes nothing, not even the manifest.

Where things go¶

There is no separate table in the code. Each preset declares its user-level layout once, next to its project layout: a provider spec in its [global] block (plus global_path on a settings sidecar), a Go preset through GlobalOutputProvider. generate --user renders the preset as for a project and maps each output onto that layout. An output the preset has no user-level location for (MCP files, plugin sidecars, a kind of content the tool has no home folder for) is dropped and counted in the plan. The table below is generated from those declarations and a test fails when it drifts (UPDATE_DOCS=1 go test ./internal/generator/userscope rewrites it).

Kinds: instructions is the root instructions file, rules a rules folder, skills, agents and commands the matching folders, settings a shared config document of the tool. At user level only hooks, permissions and managed settings are merged into a settings document, never MCP servers, and nothing is written to it when the config has none. Claude Code renders commands as skills, so they share the skills row.

Presets not in the table have no documented user-level location for anything --user writes, and are reported and skipped: aiassistant, baz, codebuff (only an MCP file), replit and xum.

Only an absolute home is used. generate --user refuses a relative $HOME.

Relocated tool homes¶

A tool whose home directory an environment variable relocates follows it: when the variable is set to an absolute path, every path in the tool's own home moves there. CODEX_HOME=/data/codex writes /data/codex/AGENTS.md and /data/codex/hooks.json, while Codex's skills stay in the shared ~/.agents/skills. The variables are CODEX_HOME, HERMES_HOME, DEEPAGENTS_HOME, KIMI_CODE_HOME, QWEN_HOME, VIBE_HOME, DSH_HOME and the others a preset's [global] home_env names. A relative value is ignored with a warning and the default location is used. The files stay recorded in the manifest, so clean --user removes them from the relocated directory, and the symlink and hand-authored-file rules apply there too.

User-level MCP servers are not generated: Claude Code and the others keep them outside the files above.

Project and user scope together¶

Both scopes are read by the harness, so the same skill name can load twice. generate --user warns about both cases:

• One harness reading several user directories (reported for the presets you configure). OpenCode reads ~/.config/opencode/skills, ~/.claude/skills and ~/.agents/skills; Cursor reads ~/.agents/skills, ~/.cursor/skills, ~/.claude/skills and ~/.codex/skills; Gemini CLI, Copilot and Codex read ~/.agents/skills (plus their own). Generating skills for claude and opencode therefore installs each skill twice for OpenCode. Keep to presets that share a directory (codex, gemini, cursor, pi all use ~/.agents/skills), or accept the duplicates.
• A skill that also exists in the project you run from. The vendor's documented precedence decides which copy runs:

Instructions files are concatenated by the harnesses rather than overridden (Claude Code and Gemini CLI load the user-level file and then the project's; Codex loads the global AGENTS.md first), so no warning is needed for them.