An agent skill that syncs your portable AI coding harness files, and one canonical set of global instructions, across machines and harnesses using git.
Built in: Claude Code, Codex, Cursor, Gemini CLI, and OpenCode. Any other harness that reads its files from your home directory can be added as a custom harness.
- Across machines: your authored agents, instructions, commands, rules, and skills travel through a private git remote. Machine-specific and generated state stays local.
- Across harnesses: one canonical instructions document (a shared core plus optional per-harness overlays) generates
CLAUDE.md,AGENTS.md,GEMINI.md, and the instructions file of every custom harness, and edits made in any of them merge back.
Deterministic scripts do every file operation and render exact diffs; the agent in your harness orchestrates and handles the semantic merging. Nothing is ever written without showing you the diff first, and No is always the default.
-
Install the skill into your harnesses:
npx git-agents@latest
Installed once, updated in-session: whenever a newer git-agents release exists, any
/git-agentscommand ends by offering the update; accept and the skill refreshes itself. -
Open your coding agent and run:
/git-agents setupSetup asks for your remote preference (GitHub CLI auto-creates a private
git-agents-remoterepo, or bring any git remote URL), then clones it to~/.git-agents. -
Converge your instructions:
/git-agents sync unify
If you skip step 2, any other subcommand routes you into setup first.
| Subcommand | What it does |
|---|---|
/git-agents setup |
One-time onboarding: remote choice, repo creation, clone. Safe to re-run. |
/git-agents sync |
Transport: your configs travel to and from the repo independently, git-native. Conflicts are resolved by the agent (reconciled when compatible, interviewed when contradictory), including a file deleted on one machine and edited on another, or a skill folder replaced by a link. Paths deleted on both sides and conflicts on excluded files settle themselves. The canonical is never involved. |
/git-agents sync unify |
The full convergence flow: transport, then merge drift into the canonical, regenerate every harness file, and push once. |
/git-agents edit <request> |
Freeform edit of your global instructions: the agent interprets the request (add, reword, remove), drafts it into the canonical in the right section, and runs the full convergence flow around it. |
/git-agents harness <request> |
Declare, change, or remove a custom harness: the agent drafts the declarations, shows the exact diff of the declarations file and the paths that start or stop syncing, then offers to sync. |
/git-agents status |
Config, canonical version, per-file state, drift, and caveats. Read-only. |
Every write is gated: the scripts render exact per-file diffs, and nothing happens until you explicitly confirm. Per harness: Claude Code and Cursor use /git-agents <subcommand>, Codex uses $git-agents <subcommand>, OpenCode invokes it through its skill tool, and Gemini CLI shows a consent prompt on skill activation, which is expected.
Your global instructions live once, inside the sync repo:
~/.git-agents/
canonical/
core.md shared by every harness
overlays/<name>.md optional per-harness extras
Each harness file is generated as core plus overlay, wrapped in ga: markers so later edits (yours or the harness's own memory writes) can be attributed and merged back. Because the canonical lives in the sync repo, it travels across machines with the ordinary push and pull.
Cursor has no global instructions file, so it receives no generated copy. This is a documented limitation, not a bug. Opt-in bridge: a one-time manual User Rule pointing Cursor at the canonical file; ask the skill about Cursor and it walks you through adding the rule, exact paths included.
Only the paths below, plus those of your custom harnesses, are synced across machines. A trailing / means the full directory tree. Files matched by git ignore rules are still included inside these explicitly selected paths.
| Harness | Synced paths |
|---|---|
| Claude Code | ~/.claude/CLAUDE.md (generated)~/.claude/agents/~/.claude/commands/~/.claude/rules/~/.claude/skills/ |
| Codex | ~/.codex/AGENTS.md (generated)~/.codex/agents/~/.agents/skills/ |
| Cursor | ~/.cursor/agents/~/.cursor/commands/~/.cursor/skills/ |
| Gemini CLI | ~/.gemini/GEMINI.md (generated)~/.gemini/agents/~/.gemini/commands/~/.gemini/skills/ |
| OpenCode | ~/.config/opencode/AGENTS.md (generated)~/.config/opencode/agents/~/.config/opencode/commands/~/.config/opencode/skills/ |
The canonical directory itself is part of the sync repo and needs no entry here. The previously synced ~/.cursor/rules/ path was removed: Cursor does not read a global rules directory.
Generated state, general settings, authentication data, caches, sessions, and managed installs outside the paths above are excluded. Everything inside a selected directory is treated as portable content, so keep machine-specific files outside it.
On Windows, a selected leaf directory junction syncs the contents of its target. Pulling into an existing junction updates that target without replacing the junction. POSIX executable state is preserved for synced files.
Inside the synced directories, some files belong to one machine: a tool writes them, a skill builds them, or the operating system leaves them. They are excluded, in both directions. Sync never copies them into the repo, never writes them into a home directory, and never overwrites or deletes them there. When a synced folder is replaced or removed, the excluded files inside it stay. A folder that holds nothing but excluded files counts as absent.
| Excluded | Why |
|---|---|
~/.claude/skills/synced/ |
Claude Code's claude.ai skill sync: its manifest, staging area, and copies of your claude.ai skills, rebuilt by each machine's app |
.trash/ anywhere |
Trash folders, such as Claude Code's ~/.claude/skills/.trash/ for removed skills |
.staging/ anywhere |
Staging areas of tools that write in steps |
~/.codex/skills/.system/ |
Codex's bundled system skills, rewritten on every Codex update (only reached by a custom harness that syncs ~/.codex/skills) |
node_modules/, __pycache__/, .venv/ anywhere |
Dependencies and caches a skill installs or builds for one machine's platform |
.git/ anywhere |
Repository metadata of a skill cloned with git; the skill's files still sync |
.DS_Store, ._*, Thumbs.db, desktop.ini |
Files macOS and Windows leave in folders |
.<name>.git-agents-incoming-*, .<name>.git-agents-backup-* |
git-agents' own temporary names, left over by an interrupted sync |
Other folders the harnesses manage, such as Cursor's built-in skills (~/.cursor/skills-cursor/), Gemini CLI extensions (~/.gemini/extensions/), and OpenCode's plugin installs, are outside the synced paths and were never synced.
To exclude more, list patterns in .git-agents-excludes at the root of the sync repo clone (~/.git-agents/.git-agents-excludes), one per line, # for comments:
# Notes I keep next to skills on this machine only
notes
*.log
.claude/skills/local-only- A pattern without a
/matches that name at any depth. - A pattern with a
/matches from your home directory. *and?match within a name, and**matches any number of folders. Matching ignores case.
The file travels with the next sync, so every machine applies the same list. A list kept on one machine only would let the other machines send the excluded files back. Or ask the agent ("stop syncing the notes folders in my skills"): it proposes the pattern and runs the sync.
Cleanup of the repo. Excluded files that an earlier version committed, or that were committed before you added an exclude, leave the repo on the next sync. The confirmation lists them under excluded. The files stay in every home directory. Machines still on an older version that keep committing them get their conflicts on those paths settled automatically.
A harness that is not built in can be declared, and from then on it is treated exactly like a built-in: every machine sharing the repo transports its paths and generates its instructions file from the canonical, whether or not the harness is installed there. Ask for it in plain words:
/git-agents harness add DeepSeek Harness: instructions in ~/.dsh/AGENTS.md, skills in ~/.dsh/skills
The agent drafts the declaration and shows the exact diff of the declarations file, with the paths that start syncing, before anything is written. Run /git-agents harness alone to list the built-in and custom harnesses.
Declarations live in .git-agents-harnesses.json at the root of the sync repo (~/.git-agents/). The file is committed and reaches every machine through an ordinary sync; there is no per-machine opt-in. Without the file, nothing changes.
{
"version": 1,
"harnesses": {
"dsh": {
"name": "DeepSeek Harness",
"instructionsFile": ".dsh/AGENTS.md",
"syncPaths": [".dsh/skills"]
}
}
}- The key is the harness id: lowercase letters, digits, and hyphens, starting with a letter, at most 32 characters. It names the overlay
canonical/overlays/<id>.mdand cannot be changed; changing it removes the harness and declares a new one. instructionsFile(optional): the harness's global instructions file.sync unifygenerates it from the canonical and merges edits back. It syncs on its own and is not repeated insyncPaths.syncPaths(optional): files or directories that only sync, like a built-in's.name(optional): the display name, defaulting to the id.- At least one of
instructionsFileandsyncPathsis required. Unknown fields make the file invalid.
The built-in harnesses, written in the same shape, make good worked examples. They are built in: they cannot be put in the declarations file, and their ids (claude-code, claude, codex, cursor, gemini-cli, gemini, opencode) cannot be used for a custom harness.
{
"claude-code": { "name": "Claude Code", "instructionsFile": ".claude/CLAUDE.md", "syncPaths": [".claude/agents", ".claude/rules", ".claude/skills", ".claude/commands"] },
"codex": { "name": "Codex", "instructionsFile": ".codex/AGENTS.md", "syncPaths": [".codex/agents", ".agents/skills"] },
"cursor": { "name": "Cursor", "syncPaths": [".cursor/agents", ".cursor/skills", ".cursor/commands"] },
"gemini-cli": { "name": "Gemini CLI", "instructionsFile": ".gemini/GEMINI.md", "syncPaths": [".gemini/agents", ".gemini/commands", ".gemini/skills"] },
"opencode": { "name": "OpenCode", "instructionsFile": ".config/opencode/AGENTS.md", "syncPaths": [".config/opencode/agents", ".config/opencode/commands", ".config/opencode/skills"] }
}Every path is relative to the home directory and written the same way on every OS: no ~, no environment variables, no per-OS variants. A harness whose location differs by OS needs one declaration per location. Every declared path must be:
- Portable: forward slashes, no
.., no empty or.segments, and every segment valid on Windows (none of< > : " | ? *, no trailing dot or space, no device names such asconornul). - At least two segments deep:
.dsh/skills, never.dshor.bashrc. - Outside reserved names: the first segment is not
.git,.git-agents, orcanonical. - Outside credential directories: not
.ssh,.gnupg,.aws,.azure,.kube,.docker,.config/gh,.config/gcloud, or.config/git, nor inside one. This list cannot be overridden. - Owned once: no path is declared twice or nested inside another, across built-in and custom harnesses, compared case-insensitively. A harness that also reads a file a built-in already generates (such as
~/.claude/CLAUDE.md) is declared without that file.
- The first sync pushes the declaration with the files, and its confirmation lists each newly synced path with its file count and total size. Other machines receive both on their next sync; a machine that already holds a different file at that path gets an ordinary conflict, resolved like any other. Declining a sync never undoes a declaration.
- The first
sync unifygenerates the new instructions file from the canonical; until thenstatusreports it as untracked. - Removing a declaration stops the sync of its paths. Its copies, overlay, and manifest entries are deleted from the repo; files in the home directory are never touched, on any machine. When the harness had an overlay, run
sync unifyafterwards.
You can also edit the file by hand in ~/.git-agents/: the next sync validates it the same way.
/git-agents status warns when something would silently break the sync:
~/.codex/AGENTS.override.mdexists and shadows the generated file.- Gemini's
context.fileNamesetting no longer includesGEMINI.md. - The Codex instructions file approaches its 32 KiB cap (Codex truncates silently at the cap).
.git-agents-harnesses.jsonis invalid. Every sync stops, for the built-in harnesses too, until the file is fixed; the caveat lists each problem, and/git-agents harnessrepairs it.
Version 1.0.0 removed the interactive TUI and the ga pull / ga push terminal commands.
- Your remote, clone, and synced files are untouched; the same
~/.git-agentsconfig keeps working. - Run
npx git-agents@latestonce to install the skill; setup detects the existing config and leaves it alone. ga pullandga pushmerged into/git-agents sync, which now moves changes in both directions in one run and resolves conflicts instead of overwriting one side.- Paths committed by older releases remain in the remote checkout for safe manual cleanup. Current sync ignores them and does not copy, stage, or commit them.
- Node.js 22 or newer, and npm
- git
- GitHub CLI (only for the GH remote option)
- At least one supported coding agent to drive the skill
git clone https://github.com/floklein/git-agents.git
cd git-agents
npm install
npm run check # typecheck, tests, build