agentdots-sync

Backup and sync local AI agent skills, rules, and instruction files (AGENTS.md, CLAUDE.md) with a Git remote. Profiles cover Claude Code, Codex, OpenCode, Grok Build, CodeBuddy, and WorkBuddy.

The tool copies files; it does not convert instruction formats between platforms.

After install, see Usage (中文使用说明).

Contents

Install

npx skills add ferbylv/agentdots-sync

gh skill install ferbylv/agentdots-sync

git clone https://github.com/ferbylv/agentdots-sync.git
python3 skills/agentdots-sync/scripts/sync.py --list-platforms

How to talk to the agent, which flags to use, and a Claude Code backup example: Usage.

Supported profiles

Profile Default root Default assets Notes
codex ~/.codex AGENTS.md, rules, skills Preserves the existing .codex_backups location.
claude-code ~/.claude CLAUDE.md, rules, skills Alias: claude.
opencode ~/.config/opencode skills Select configuration files explicitly because they may contain environment-specific values.
grok-build ~/.grok skills Alias: grok; select configuration files explicitly.
codebuddy-code ~/.codebuddy rules, skills Alias: codebuddy.
workbuddy explicit skills Point --root at an unpacked local skill/package workspace; WorkBuddy UI import remains a separate step.
custom explicit explicit For another Agent Skills-compatible layout.

These defaults target user-level assets. For a project profile, pass the project as --root and select exact project-relative paths with repeated --asset options.

Profile layouts follow the current official documentation for Claude Agent Skills, OpenCode Skills, Grok Build Skills, CodeBuddy Code Skills, and WorkBuddy skill import. Re-check those sources before a release because platform directories and import behavior can change.

Safety model

  • Planning, profile listing, and diagnostics are read-only.
  • Mutating modes require --yes.
  • Existing selected local assets are backed up before apply, restore, or rollback replacement.
  • Rollback uses a validated manifest and restores only requested assets present in that manifest.
  • Mutating commands are serialized per root with .meta-sync-lock.
  • Selected assets cannot escape the root or use absolute/cross-boundary symlinks.
  • Push stages and verifies only selected paths; it never force-pushes.
  • Errors redact common URL credentials, bearer tokens, and credential query parameters.

Requirements

  • Python 3.9 or newer.
  • Git on PATH for remote operations.
  • A local execution surface with access to the selected root. Browser-only chat products cannot use this tool to synchronize files on the user's computer.

Inspect profiles and prerequisites

python3 skills/agentdots-sync/scripts/sync.py --list-platforms
python3 skills/agentdots-sync/scripts/sync.py --platform claude-code --doctor
python3 skills/agentdots-sync/scripts/sync.py --platform opencode --plan
python3 skills/agentdots-sync/scripts/sync.py --platform claude-code --apply --plan \
  --remote https://example.com/account/agent-assets.git --branch main

The default platform remains codex, so existing commands without --platform keep their previous root, assets, and backup location.

Apply, push, and rollback

Run a plan first and verify its canonical platform, root, asset list, backup directory, remote, and branch. Then run only the explicitly approved operation:

python3 skills/agentdots-sync/scripts/sync.py --platform claude-code --restore --yes \
  --remote https://example.com/account/agent-assets.git --branch main

python3 skills/agentdots-sync/scripts/sync.py --platform grok-build --push --yes \
  --remote https://example.com/account/agent-assets.git --branch main \
  --message "Update Grok skills"

python3 skills/agentdots-sync/scripts/sync.py --platform codebuddy-code --rollback --yes

Override defaults when needed:

python3 skills/agentdots-sync/scripts/sync.py --platform custom --root /path/to/agent-config \
  --asset instructions.md --asset skills --plan

python3 skills/agentdots-sync/scripts/sync.py --platform opencode --root /path/to/project \
  --asset AGENTS.md --asset .opencode/skills --plan

--backup-dir accepts only a safe child path within the selected root. Non-Codex profiles use .meta-sync-backups by default.

Testing and release checks

python3 -m unittest discover -s tests -v
python3 skills/agentdots-sync/scripts/sync.py --help
python3 skills/agentdots-sync/scripts/sync.py --list-platforms

Before publishing, validate skills/agentdots-sync/SKILL.md, inspect the release file list, and test each platform profile in an isolated temporary root. Do not include .DS_Store, credentials, real remotes, generated backups, or lock files.