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:
- Creating one real
.harness/directory with the canonical files. - Writing relative symlinks everywhere each agent expects to look.
- 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 — inspect symlink health
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,
mhaborts with an error rather than deleting your data. --forceis 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.