harness-sync

harness-sync is a CLI that syncs AI coding harness skills from a private GitHub catalog into your current project. Supported harnesses: OpenCode, Claude Code, and Codex CLI.

Prerequisites

• GitHub CLI (gh) installed and authenticated.
• Access to the catalog repo you want to use.

Installation

Install the CLI globally using your preferred package manager:

npm i -g harness-sync
pnpm add -g harness-sync
bun add -g harness-sync

Verify the install:

harness-sync -h

Quick Start

1. Configure your catalog repo.
2. List skills to see what is available.
3. Apply skills to your project.

harness-sync init
harness-sync list
harness-sync apply

Commands

harness-sync init

Prompts for the catalog repo in owner/repo format and stores it locally.

harness-sync init

harness-sync list

Lists skills in the catalog with applied status for the current project.

harness-sync list

harness-sync apply

Interactive flow to select harnesses and skills, then apply them.

harness-sync apply

harness-sync

Alias for the interactive apply flow.

harness-sync

harness-sync --version

Prints the CLI version.

harness-sync --version

harness-sync --help

Prints usage help.

harness-sync --help

Non-Interactive Apply

Flags are supported only for harness-sync apply.

harness-sync apply --skills alpha,beta --harnesses opencode,claude,codex --yes

Flags

• --skills <id1,id2>: Comma-separated skill IDs.
• --harnesses <opencode,claude,codex>: Comma-separated harness targets.
• --yes or -y: Auto-confirm overwrites. Requires both --skills and --harnesses.

Catalog Structure

The catalog repo must contain a skills/ directory. Each skill is a folder with a SKILL.md file containing YAML frontmatter:

---
name: Alpha
description: Short description of the skill
---

Example layout:

catalog-repo/
  skills/
    alpha/
      SKILL.md
      ...other files

Where Skills Are Applied

Skills are copied into the current project root.

• OpenCode: .opencode/skills/<skill-id>
• Claude Code: .claude/skills/<skill-id>
• Codex CLI: .codex/skills/<skill-id>

If a destination already exists, the CLI prompts before overwriting unless --yes is used.

Configuration File

The catalog repo setting is stored in:

~/.config/harness-sync/config.json

If XDG_CONFIG_HOME is set, the path becomes:

$XDG_CONFIG_HOME/harness-sync/config.json

Notes

• The catalog is fetched via gh using a shallow clone.
• The tool attempts to clone main first, then falls back to master.
• Temporary catalog clones are cleaned up automatically.