harness-sync · one config, every harness

The problem

You run claude-code, kilo, crush, opencode, goose, cagent, zed — each keeps its own copy of the same config.

without harness-sync

✕same skill markdown, duplicated seven ways
✕same agent definitions, rewritten per harness
✕same MCP registry, seven different key names (mcpServers, mcp, context_servers…)
✕same gateway URL, hand-copied into seven files
✕edit once, forget the others, things break

with harness-sync

→one canonical tree under git version control
→per-harness adapters render native config formats
→3-way merge via git merge-file
→secrets via ${VAR} env-var substitution, never stored
→git rollback on every apply

What it does

→
Canonical tree. Profiles, skills, agents, mcp servers, and instructions in a single git-managed directory.
→
Native adapters. Each harness gets its correct keys and file types — no lowest-common-denominator config.
→
3-way merge. git merge-file semantics — disjoint changes merge cleanly, conflicts produce .rej files.
→
Profiles. Bundle gateway URL, model allowlist, and upstream keys — switch with one command.
→
Secret safety. Env-var substitution at render time. Secrets never written to disk or canonical tree.
→
Auto-detection. Detects installed harnesses. Only touches what's relevant on your machine.
→
Dry-run preview. Diff every target file before writing anything to disk.
→
Git rollback. Revert the last n applies. Full version history in local git.
→
Non-destructive overlay. Only managed keys are written. Your hooks, permissions, and editor settings survive.

Supported harnesses

Each adapter grounded against real config files and upstream docs.

harness	manages	note
claude-code	mcp · skills · instructions	provider config managed by Anthropic directly
crush	mcp · skills · providers · models	full gateway rendering with provider map
kilo	mcp · skills · providers · models	small model + provider map config
opencode	mcp · skills · providers · models · instructions	JSONC config with instructions merging
goose	mcp · skills · providers · models	YAML with extensions map
cagent	mcp · providers · models · instructions	starter YAML with per-agent model
zed	mcp · providers · models	context servers in settings.json

Install

one-liner (recommended)

$ curl -fsSL https://raw.githubusercontent.com/\
    lukaszraczylo/harness-sync/main/install.sh | bash

Picks the right release for OS/arch, verifies SHA-256, drops binary in ~/.local/bin.

homebrew

$ brew install lukaszraczylo/taps/harness-sync

from source

$ git clone https://github.com/lukaszraczylo/harness-sync
$ make build && make install

Requires Go 1.24+ and git on $PATH.

Usage

# 1. see what's installed
$ harness-sync detect

# 2. import from detected harnesses into canonical tree
$ harness-sync init

# 3. render canonical tree to all harness configs
$ harness-sync apply
$ harness-sync apply --dry-run        # preview without writing
$ harness-sync diff                  # same as apply --dry-run
$ harness-sync profile list           # list profiles
$ harness-sync profile use work       # switch active profile
$ harness-sync rollback 2             # git revert last 2 applies
$ harness-sync update                 # pull latest release

flags

flag	effect
--dry-run	show plan, write nothing
--force	overwrite without merge
--yes	skip confirmation prompt
--from a,b	pick source adapters for init
--no-prompt	take all detected sources

Architecture

Single Go binary. ~7,400 LOC. 174 passing tests. 18 packages.

canonical tree

~/.config/harness-sync/  (git)
├── profiles/<name>.yaml
├── skills/<name>/SKILL.md
├── agents/<name>.md
├── mcp.yaml
└── instructions/global.md

merge model

base   ← state/  (last render)
ours   ← rendered (what we'd write now)
theirs ← on disk  (what's actually there)

disjoint → clean merge, write file
overlap  → .rej file, exit non-zero