Skip to main content

multi-harness 🔗

One project. Many coding agents. Zero duplication.

mh is a CLI that keeps your skills, subagents, and project instructions in a single canonical .harness/ directory and materialises per-agent symlinks so every agent sees the paths it expects — no copy-paste, no drift.

Supported agents: Claude Code · OpenAI Codex CLI · OpenCode · GitHub Copilot · Google Antigravity


✨ Why multi-harness?

Each coding agent looks for instructions, skills, and subagents in different places: CLAUDE.md, .github/copilot-instructions.md, AGENTS.md, .claude/skills/, .codex/skills/ …

Without mh you either duplicate these files across every agent-specific location or keep them in sync by hand. mh solves this by:

  1. Creating one real .harness/ directory with the canonical files.
  2. Writing relative symlinks everywhere each agent expects to look.
  3. Detecting an existing single-agent project and migrating it automatically.

📦 Installation

pip install multi-harness

Verify the install:

mh --help

🚀 Quick start

cd my-project
mh init

That's it. mh detects which agents are already configured, migrates their files into .harness/, and creates symlinks for all five supported agents.


📖 Commands

mh init — bootstrap or migrate a project

mh init                                      # all five agents, current directory
mh init --agents claude,codex                # register only two agents
mh init --template ./AGENTS_TEMPLATE.md      # seed AGENTS.md from a template file
mh init --force                              # re-create symlinks idempotently (safe)
mh init /path/to/project                     # target a different directory

On first run mh init:

  • Creates AGENTS.md (or uses your --template) as the shared project instructions file.
  • Creates .harness/skills/ and .harness/agents/ as the shared canonical directories.
  • Writes relative symlinks for every registered agent (see layout below).
  • Records the registered agents in .harness/config.toml.

If exactly one agent is already configured, mh init migrates its files into .harness/ before creating symlinks — your existing work is preserved, not overwritten.


mh add — register new agents

mh add copilot                               # add a single agent
mh add opencode antigravity                  # add multiple agents at once

Creates the symlinks for the new agent(s) and updates .harness/config.toml. Requires mh init to have been run first.


mh remove — unregister agents

mh remove codex                              # remove one agent
mh remove opencode copilot                   # remove several at once

Removes the agent's symlinks (instructions, skills, subagents) without touching any file inside .harness/. Your shared content is never deleted.


mh status                                    # check current directory
mh status /path/to/project                   # check another directory

Reports the state of every symlink for every registered agent:

Status Meaning
✅ ok Symlink exists and resolves correctly
❌ missing Symlink is absent
💔 broken Symlink exists but target doesn't resolve
⚠️ detached A real file/dir sits where a symlink should be

🗂️ Layout produced by mh init

my-project/
├── AGENTS.md                          ← canonical shared instructions (real file)
├── CLAUDE.md                         → AGENTS.md
├── .harness/
│   ├── config.toml                    ← registered agents list
│   ├── skills/                        ← shared skills (real dir)
│   └── agents/                        ← shared subagents (real dir)
├── .claude/
│   ├── skills                        → ../.harness/skills
│   └── agents                        → ../.harness/agents
├── .codex/
│   ├── skills                        → ../.harness/skills
│   └── agents                        → ../.harness/agents
├── .opencode/
│   ├── skills                        → ../.harness/skills
│   └── agent                         → ../.harness/agents
├── .github/
│   ├── copilot-instructions.md       → ../AGENTS.md
│   ├── skills                        → ../.harness/skills
│   └── agents                        → ../.harness/agents
├── .agents/
│   └── skills                        → ../.harness/skills
└── .subagents                        → .harness/agents

All symlinks are relative, so the tree is fully portable across machines and paths.


🔄 Typical workflow

# 1. Bootstrap a new project
mh init --agents claude,codex

# 2. Add an agent later
mh add copilot

# 3. Check everything is wired up correctly
mh status

# 4. Remove an agent you no longer use
mh remove antigravity

Write your instructions once in AGENTS.md, drop skills into .harness/skills/, and place shared subagents in .harness/agents/ — every registered agent picks them up automatically.


🛡️ Safety guarantees

  • Symlinks never overwrite real files. If a real file or directory already exists where a symlink should go, mh aborts with an error rather than deleting your data.
  • --force is safe. It re-creates symlinks but still refuses to touch real files.
  • Migration is non-destructive. Files are moved into .harness/; nothing is deleted.

Metadata

Release files for multi-harness 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for multi-harness 0.1.0
File Size Uploaded Provenance Actions
multi_harness-0.1.0.tar.gz 14.8 kB Without provenance Details for multi_harness-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for multi-harness 0.1.0
File Interpreter ABI Platform Actions
multi_harness-0.1.0-py3-none-any.whl Python 3 none any Details for multi_harness-0.1.0-py3-none-any.whl

Total release size: 27.0 kB

Release files / multi_harness-0.1.0.tar.gz

Download URL multi_harness-0.1.0.tar.gz
Size 14.8 kB
Tags Source
SHA-256 checksum
How to use checksums
34e1941f8637f88a42c6321d3dc786764f2462ab232ee488c92a9ac1510a0963
BLAKE2b-256 checksum
How to use checksums
21e569dba0fc8ca80ce50998df7b59c2a416ad579f6c55df63ba6eb4f0468cc0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.4

Release files / multi_harness-0.1.0-py3-none-any.whl

Download URL multi_harness-0.1.0-py3-none-any.whl
Size 12.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
97d6b81233f1441526c16e1050fcbc0e10529c7166601505db88e8c97e05200b
BLAKE2b-256 checksum
How to use checksums
b508d7d844a030b9dd106a1876f63eada722c303ba60eb4eb1c863c817b4708b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.4

Security for multi-harness 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page