Skip to content
Back to search

agent-sync

Keep Claude Code, Codex and Cursor in step: skills, agents, model roles, MCP servers, plugins and CLI updates, once a day.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 20 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Kasakir-AI/agent-sync with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Kasakir-AI/agent-sync'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kasakir-ai--agent-sync/badge.svg)](/listings/kasakir-ai--agent-sync)

HTML

<a href="/listings/kasakir-ai--agent-sync"><img src="/api/listings/kasakir-ai--agent-sync/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Python 3.11+, git, and Node (for `npx`). Without Homebrew or [pipx](https://pipx.pypa.io), give it a virtual environment of its own: `python3 -m venv ~/.local/share/agent-sync/venv && ~/.local/share/agent-sync/venv/bin/pip install git+https://github.com/Kasakir-AI/agent-sync.git`, then link `~/.local/share/agent-sync/venv/bin/agent-sync` into a folder on your PATH.

brew install kasakir-ai/tap/agent-sync      # or: pipx install git+https://github.com/Kasakir-AI/agent-sync.git
agent-sync setup                  # install whatever is missing: git, Node, Claude Code, Codex, Cursor Agent
agent-sync config                 # change the settings by answering questions (optional)
agent-sync run --dry-run          # see what it would change first
agent-sync run --force --echo     # first run, with every step on screen
agent-sync install --launcher     # schedule it (hourly + at login, works once a day); --launcher adds
                                  # a double-click "Agent Upkeep" to the Desktop (macOS)
agent-sync launcher               # just the Desktop launcher, if you want it without reinstalling

`agent-sync setup` installs only what is missing, and asks first (`--dry-run` lists it, `--yes` skips the question). On a Mac without Homebrew it installs Homebrew first (that needs an administrator's password); then git, Node and the three CLIs come from Homebrew, the CLIs as the casks `claude-code`, `codex` and `cursor-cli`. Where Homebrew isn't available to your account, the CLIs come from their official per-user installers into `~/.local/bin` (no administrator needed), and setup tells you how to get git or Node. The daily run never installs anything; it notes a missing CLI instead.

On Linux, `agent-sync install` sets up a systemd user timer instead; run `loginctl enable-linger` if it should also run while you are logged out.

`agent-sync run --dry-run` shows everything a run would change (files it would write, commands it would run) and changes nothing: no log, no state, no package cache. `agent-sync status` shows the last run, the log location and the installed CLI versions, and which Claude Code plugins have skills you could offer to Codex and Cursor. `agent-sync uninstall` removes the schedule and the launcher (and switches the launcher setting off, so the next run doesn't bring it back).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 158 lines
  1. # agent-sync
  2. Keep **Claude Code**, **Codex** and **Cursor** in step on one Mac (or Linux machine). Pick one of them as the source of truth, and
  3. agent-sync makes the other two match it, once a day:
  4. - **Skill packages** (for example [pstack](https://github.com/backnotprop/pstack)) are installed and updated for
  5. all three tools from one shared copy, with the [`skills`](https://www.npmjs.com/package/skills) CLI.
  6. - **Agents** that ship with a package (`agents/*.md`) are mirrored into each tool's own format: Claude Code
  7. `~/.claude/agents`, Codex `~/.codex/agents/*.toml`, and a small local Cursor plugin, because Cursor only reads
  8. custom agents from projects and plugins. Each tool's copy runs on a model you choose for that tool, and you can
  9. add your own notes to an agent's prompt. Skills a package stops shipping are uninstalled.
  10. - **Your own skills** (the ones you made in the source tool, not from a package) are copied to the other tools.
  11. A copy is marked as agent-sync's, so it follows the source and goes away with it; a folder you made by hand in
  12. the other tool is never touched.
  13. - **Skills inside Claude Code plugins** (optional, per plugin): the skills of the plugins you pick are copied to
  14. Codex and Cursor. Most plugins only make sense in Claude Code, so none are copied until you name them in
  15. `plugin_skills`.
  16. - **pstack model roles** (`feature, refactoring: <model>` and the rest) are copied from the source tool's
  17. `pstack-models` file to the others, and each tool keeps its own notes on how to run each model.
  18. - **MCP servers** at user level are added to the tools that don't have them yet. Nothing is ever deleted, and
  19. servers that already exist are left alone.
  20. - **Global instructions** (optional): `CLAUDE.md` is copied into Codex's `AGENTS.md` (in a marked block, so the
  21. file's own text stays) and into a Cursor rule that always applies, or `AGENTS.md` the other way round.
  22. - **Plugins**: Claude Code's plugin marketplaces and the plugins you installed, the Git plugin marketplaces you
  23. added to Codex, and the Cursor plugin marketplaces you added (Cursor manages its built-in ones itself).
  24. - **The three CLIs** are updated: Claude Code and Cursor Agent through Homebrew when installed that way,
  25. otherwise through their own updaters, and Codex with `codex update`.
  26. - **agent-sync itself** is updated the way you installed it: `brew upgrade` for the Homebrew formula,
  27. `pipx upgrade`, or a fresh install from GitHub for a pip install from the repository.
  28. - **A double-click launcher** (macOS, optional): "Agent Upkeep" on the Desktop runs the upkeep with every step on
  29. screen, then lets you press `s` to change the settings. Every run puts it back if it is missing and rewrites it
  30. when a new version of agent-sync changes it.
  31. - **A small log** with a timestamp on every line keeps the last 7 days, and warns when a model you listed in
  32. `warn_models` (one you have no subscription for, say) shows up in any tool's settings.
  33. It runs hourly and at login but only does the work once every 20 hours, so a day the Mac was off is caught up
  34. soon after it starts.
  35. > Status: 0.4.0. macOS (launchd) and Linux (systemd user timer). See the [roadmap](docs/ROADMAP.md).
  36. ## Install
  37. Requires Python 3.11+, git, and Node (for `npx`). Without Homebrew or
  38. [pipx](https://pipx.pypa.io), give it a virtual environment of its own:
  39. `python3 -m venv ~/.local/share/agent-sync/venv && ~/.local/share/agent-sync/venv/bin/pip install
  40. git+https://github.com/Kasakir-AI/agent-sync.git`, then link `~/.local/share/agent-sync/venv/bin/agent-sync` into a
  41. folder on your PATH.
  42. ```sh
  43. brew install kasakir-ai/tap/agent-sync # or: pipx install git+https://github.com/Kasakir-AI/agent-sync.git
  44. agent-sync setup # install whatever is missing: git, Node, Claude Code, Codex, Cursor Agent
  45. agent-sync config # change the settings by answering questions (optional)
  46. agent-sync run --dry-run # see what it would change first
  47. agent-sync run --force --echo # first run, with every step on screen
  48. agent-sync install --launcher # schedule it (hourly + at login, works once a day); --launcher adds
  49. # a double-click "Agent Upkeep" to the Desktop (macOS)
  50. agent-sync launcher # just the Desktop launcher, if you want it without reinstalling
  51. ```
  52. `agent-sync setup` installs only what is missing, and asks first (`--dry-run` lists it, `--yes` skips the
  53. question). On a Mac without Homebrew it installs Homebrew first (that needs an administrator's password); then
  54. git, Node and the three CLIs come from Homebrew, the CLIs as the casks `claude-code`, `codex` and `cursor-cli`.
  55. Where Homebrew isn't available to your account, the CLIs come from their official per-user installers into
  56. `~/.local/bin` (no administrator needed), and setup tells you how to get git or Node. The daily run never
  57. installs anything; it notes a missing CLI instead.
  58. On Linux, `agent-sync install` sets up a systemd user timer instead; run `loginctl enable-linger` if it should also
  59. run while you are logged out.
  60. `agent-sync run --dry-run` shows everything a run would change (files it would write, commands it would run)
  61. and changes nothing: no log, no state, no package cache. `agent-sync status` shows the last run, the log
  62. location and the installed CLI versions, and which Claude Code plugins have skills you could offer to Codex and
  63. Cursor. `agent-sync uninstall` removes the schedule and the launcher (and switches the launcher setting off, so
  64. the next run doesn't bring it back).
  65. ## Configure
  66. The easy way: run `agent-sync config` (or `agent-sync settings`). It shows every setting with its current value,
  67. explains each one with examples, and asks what you want to change: the source tool, skill packages, which
  68. plugins' skills go to Codex and Cursor, which parts to keep in step, agent models and notes, model warnings,
  69. update and install commands, extra steps, and the pstack model roles. It also opens your global instructions in
  70. your editor. Nothing is written until you save; saving keeps the comments in your file, leaves the old one next to
  71. it as `config.toml.bak`, and then offers a dry run so you can see what the next upkeep would do.
  72. Or edit the file yourself: copy [`config.example.toml`](config.example.toml) to `~/.config/agent-sync/config.toml`
  73. and change what you need. Every key is optional:
  74. | key | default | what it does |
  75. | --- | --- | --- |
  76. | `source` | `"claude"` | the tool the others mirror |
  77. | `skill_packages` | `["backnotprop/pstack"]` | GitHub skill packages to install for all three tools |
  78. | `skills_cli` | `"skills@latest"` | the `skills` CLI version (pin one to hold it) |
  79. | `remove_dropped_skills` | `true` | uninstall skills a package no longer ships |
  80. | `mirror_roles` / `mirror_mcp` / `mirror_skills` / `update_plugins` | `true` | switch parts off |
  81. | `skip_skills` | `[]` | your own skills that stay in the source tool only |
  82. | `plugin_skills` | `[]` | Claude Code plugins whose skills are copied to Codex and Cursor, e.g. `["my-plugin"]` or `["my-plugin@marketplace"]` |
  83. | `mirror_instructions` | `false` | copy the source tool's global instructions to the others |
  84. | `warn_models` | `[]` | warn when a model name containing one of these appears, e.g. `["preview-"]` |
  85. | `update_clis` | `true` | `false`, or a list such as `["claude", "codex"]` |
  86. | `[cli_commands]` | none | your own update command for a CLI, e.g. `codex = ["npm", "install", "-g", "@openai/codex@latest"]` |
  87. | `[install_commands]` | none | your own install command for `agent-sync setup`, per item: `homebrew`, `git`, `node`, `claude`, `codex`, `cursor` |
  88. | `[[extra_steps]]` | none | your own commands, run at the end of every upkeep |
  89. | `update_self` | `true` | update agent-sync itself (Homebrew, pipx, or a pip install from GitHub) |
  90. | `launcher` | `false` | keep the double-click "Agent Upkeep" on the Desktop and up to date (macOS); `install --launcher` and `agent-sync launcher` switch it on |
  91. | `log_days` | `7` | how long log lines are kept |
  92. | `[agent_models]` | `opus` / `claude-opus-5-5-high-fast` / `gpt-6.2-sol` | the model each tool's copy of an agent uses |
  93. | `[agent_notes]` | none | text added to the end of an agent's prompt in every tool, e.g. `poteto-agent = "..."` |
  94. A misspelled setting is an error, not silently ignored. On Linux the config and state follow `XDG_CONFIG_HOME`
  95. and `XDG_STATE_HOME` when set.
  96. ## Make it yours
  97. - **Settings first.** Most changes need only the config file, and `agent-sync config` walks you through them:
  98. other skill packages (`skill_packages = ["you/your-skills", "backnotprop/pstack"]`), another source tool, your
  99. own models for each tool's agents, plugin skills for Codex and Cursor, parts switched off, your own update
  100. commands, notes on agents, or extra steps at the end.
  101. - **Try changes safely.** `agent-sync run --dry-run` after every config change shows exactly what would happen
  102. (`agent-sync config` offers it after you save).
  103. - **Change the code.** Each part is one small module in `agent_sync/` with no dependencies: `agents.py` (agent
  104. formats per tool), `skills.py` (your own skills, plugin skills, dropped package skills), `roles.py` (pstack
  105. model roles), `mcp.py` (MCP servers), `instructions.py` (global instructions), `tools.py` (skill packages,
  106. plugins, CLI updates, extra steps), `checks.py` (warnings), `schedule.py` (launchd, systemd, launcher),
  107. `setup.py` (installing what is missing), `configure.py` and `tomledit.py` (the settings editor), `cli.py` (the
  108. order of the steps). To add a step, write a function that takes `log` and `dry`, never writes when `dry` is
  109. true, and call it from `run()` in `cli.py`. `tests/` shows how to test a part against a throwaway home folder
  110. (`python -m pytest`).
  111. ## Moving from your own upkeep scripts
  112. If you already keep the tools in step with scripts of your own, move what is personal to your machine into the
  113. config file, which stays on your machine: notes you add to agents go in `[agent_notes]`, commands only you need
  114. go in `[[extra_steps]]`, models you never want in `warn_models`. Then:
  115. 1. `agent-sync run --dry-run` until it lists only changes you expect (ideally none).
  116. 2. Stop and remove your old scheduled job, so two jobs never write the same files.
  117. 3. `agent-sync run --force --echo`, then `agent-sync install --launcher`.
  118. ## What it changes
  119. | tool | files |
  120. | --- | --- |
  121. | Claude Code | `~/.claude/skills/*` (links and copies), `~/.claude/agents/*.md`, `~/.claude/rules/pstack-models.md`, `~/.claude.json` (`mcpServers`), `~/.claude/CLAUDE.md` (block, opt-in) |
  122. | Codex | `~/.agents/skills/*`, `~/.codex/agents/*.toml`, `~/.agents/pstack-models.md`, `~/.codex/config.toml` (`[mcp_servers.*]`, appended), `~/.codex/AGENTS.md` (block, opt-in) |
  123. | Cursor | `~/.agents/skills/*`, `~/.cursor/plugins/local/<package>-agents/`, `~/.cursor/rules/pstack-models.mdc`, `~/.cursor/mcp.json`, `~/.cursor/rules/agent-sync-instructions.mdc` (opt-in) |
  124. State and the package checkouts live in `~/.local/state/agent-sync/`. The log is `~/Library/Logs/agent-sync.log`
  125. on macOS and `~/.local/state/agent-sync/agent-sync.log` on Linux. The schedule is
  126. `~/Library/LaunchAgents/io.github.agent-sync.plist` or `~/.config/systemd/user/agent-sync.{service,timer}`.
  127. ## Safety
  128. Read [SECURITY.md](SECURITY.md). In short: skill packages and the `skills` CLI run with your agents' full
  129. permissions, so only add packages you trust, and pin `skills_cli` if you don't want new releases picked up
  130. automatically.
  131. ## License
  132. MIT, see [LICENSE](LICENSE). pstack and the `skills` CLI are separate projects with their own licenses.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.