Skip to Content
AdunemDocs
GuidesCLI referenceHelp

harness

Share your coding-agent setup, and use ones shared with you: list, serve, publish, install and ask harnesses.

A harness is a coding-agent setup you share on its own: an instructions file (CLAUDE.md or AGENTS.md), skills, and the MCP servers it uses. adunem harness has the commands to create one, share it, and use ones other people shared with you. The Harnesses guide explains the idea. This page covers the commands.

There are two kinds, and you choose when you share:

KindHow people use itWhat they can see
LiveIt keeps running on your machine. People ask it questions and call the tools you offer.Answers and tool results, never your files.
PackageYou publish versions, and people install a copy into their own Claude Code or Codex.Every file in it. Their own model runs it.

You share a harness from the Harnesses page, by email, key or space. The commands here create and serve it.

Commands

CommandWhat it does
harness listLists your harnesses and ones shared with you.
harness initWrites adunem-harness.yaml from what a folder has.
harness serveServes a live harness from this machine.
harness addAdds a harness key you were given to your list.
harness askAsks a live harness a question.
harness removeRemoves a shared harness from your list.
harness packBuilds a package bundle file.
harness publishPublishes a new version of a package harness.
harness installInstalls a package harness.
harness updateUpdates an installed package harness.
harness uninstallRemoves an installed package harness.

Every command that talks to Adunem needs you to be signed in and takes --gateway, -g <url> (default: your last gateway). A harness is named handle/name, after its owner's handle. A bare name works too when only one harness has it.

The harness folder and adunem-harness.yaml

A harness is a folder with an adunem-harness.yaml file. harness init writes it for you.

adunem-harness.yaml
schema_version: 1
name: code-reviewer
version: 0.1.0
description: Reviews pull requests the way our team does
instructions: CLAUDE.md
skills:
  - .claude/skills
mcp_servers:
  github:
    command: npx
    args: [-y, "@modelcontextprotocol/server-github"]
    env: [GITHUB_TOKEN]
tools:
  - github/search_issues
ask_before:
  - github__search_issues

schema_versionintegerdefault: 1

Only 1 is supported.

namestringrequired

Lowercase letters, numbers and -, starting with a letter or number, up to 63 characters.

versionstringdefault: none

Package harnesses: the version publish uploads, as major.minor.patch such as 0.1.0. Use a higher one each time.

descriptionstringdefault: none

What the harness is good at, up to 1000 characters. People see it in their lists.

instructionsstringdefault: none

Path to the instructions file, relative to the folder (CLAUDE.md or AGENTS.md).

skillslist of stringsdefault: []

Folders of skills, relative to the harness folder. Each skill is a subfolder with a SKILL.md. Up to 32.

fileslist of stringsdefault: []

Package harnesses: other files or folders to ship, such as an MCP server's script. Up to 64.

mcp_serversmapdefault: {}

MCP servers the harness uses, started on your machine (live) or on the installer's (package). Up to 32. Each has command, args (up to 64) and env, a list of environment variable names to pass through. Secrets are never stored here: only the names.

toolslist of stringsdefault: []

Live harnesses: the MCP tools to offer people besides ask, written as server/tool, where server is one of your mcp_servers. Nothing else is ever offered, and when you share, you still tick which tools each person gets. Up to 128.

ask_beforelist of stringsdefault: []

Live harnesses: tools that ask you, in the terminal where harness serve runs, before each call by someone else. Use ask or server__tool. They must also be offered. A call you do not answer within a minute, or when there is no terminal, is refused.

Unknown keys are rejected.

list

Shows your harnesses and the ones shared with you, like the Harnesses page.

adunem harness list
My harnesses
  alice/code-reviewer  [Live]
    online · shared with 2 people and 1 space
Shared with me
  bob/release-notes  [Package]
    v1.2.0 · by Bob

init

Writes adunem-harness.yaml in a folder from what is there: CLAUDE.md or AGENTS.md, skill folders (.claude/skills or skills), and the MCP servers in .mcp.json (their environment variable names only). It offers no tool to anyone until you list it under tools. It stops if the file already exists.

adunem harness init [folder] [--name <name>] [--description <text>]

folderpathdefault: .

The harness folder.

--nametextdefault: the folder's name

The harness's name.

--descriptiontextdefault: none

What it is good at.

serve

Serves a live harness from your machine. People you share it with get answers and tool results, not your files. It keeps running and connected until you press Ctrl-C.

adunem harness serve [folder] [--client claude-code|codex] [--gateway <url>] [--yes]

folderpathdefault: .

The harness folder.

--clienttextdefault: claude-code

Which assistant answers: claude-code or codex.

--yesflagdefault: off

Do not ask for confirmation (the Codex warning below).

--gateway, -gtextdefault: your last gateway

Which Adunem to serve on.

The first time, it creates the live harness on your account. After that, the same harness (and its shares) is reused. It prints what it offers:

serving code-reviewer with claude-code; offering: ask, github__search_issues
  asks you here first: github__search_issues

How questions are answered, using your own Claude Code or Codex:

  • ask answers with your assistant, headless, using the harness's instructions and skills and nothing else of your setup. Each call is capped at $0.50 (change it with ADUNEM_HARNESS_MAX_USD) and at about 5 minutes.
  • With Claude Code, it runs with no built-in tools at all (no files, shell or web), in an empty folder, and only with the MCP tools you offered. This is the most private option.
  • With Codex, it always has a shell. It runs read-only in an empty folder, but people's questions could still make it read files on your machine. serve warns you and asks first, unless you pass --yes.

To keep it online without a terminal, use connect --code with a harness, or plain adunem and Share my harness. Both install a login service that runs harness serve --yes with Claude Code.

add

Adds a harness key (it starts with amhk_) to your list. It asks for the key without showing it, or reads ADUNEM_HARNESS_KEY, so the key never lands in your shell history.

adunem harness add
Harness key:
✓ added bob/release-notes to your list
→ next: `adunem harness ask bob/release-notes "…"`, or open it in `adunem chat`

ask

Asks a live harness, yours or one shared with you, and prints its answer.

adunem harness ask <name> <prompt> [--lend <folder>] [--yes]

nametextrequired

The harness, as handle/name.

prompttextrequired

Your question. Quote it.

--lendpathdefault: none

Lend a folder of yours for this one call. The harness, running on its owner's machine, can list, read and search files in it, and propose edits. You approve each edit in your terminal, and nothing runs on your machine. See below.

--yesflagdefault: off

Lend without showing the notice first.

adunem harness ask alice/code-reviewer "What does our retry policy say?"

Lending a folder

With --lend, the CLI first tells you what you are about to share and asks to confirm. While the call runs:

  • The harness can list, read and search files in the folder. Its owner's model sees what it reads.
  • Kept out, always: anything outside the folder (or reached through a link), files git ignores, .env* files, keys and other secrets, .git, and files over 200 KB.
  • Each edit it proposes is shown as a diff, and waits for your yes.
  • When it ends, it prints what was read and changed.
adunem harness ask alice/code-reviewer "Review the error handling" --lend .

remove

Removes a harness that was shared with you from your list. This does not revoke anything: only the owner can.

adunem harness remove <name>

pack

Builds a package bundle, a .tar.gz that holds only the paths the manifest declares, and prints its contents. Packing the same folder twice gives the same bytes, so the same SHA-256 hash. publish does this for you. Use pack to see what would be shipped.

adunem harness pack [folder] [--out <path>]

folderpathdefault: .

The harness folder.

--outpathdefault: <name>-<version>.tar.gz

Where to write the bundle.

✓ wrote code-reviewer-0.1.0.tar.gz (2411 bytes, tier 0)
  sha256 9c1f…
  CLAUDE.md
  adunem-harness.yaml

Bundles have a risk tier, from what is inside: tier 0 is instructions only, tier 1 adds MCP servers, tier 2 includes executable files (scripts, hooks or binaries anywhere). A bundle is at most 5 MB and 500 files, has no symlinks, and is refused if it looks like it contains a secret such as a private key or an API token.

publish

Packs the folder and uploads it as a new version for people to install. The first time, it creates the package harness on your account.

adunem harness publish [folder] [--yes] [--gateway <url>]

folderpathdefault: .

The harness folder. The manifest needs a version.

--yesflagdefault: off

Do not ask for confirmation.

Every file in a package is readable by anyone you share it with. For a private recipe, serve it live instead.

✓ published code-reviewer 0.1.0 (tier 0, sha256 9c1f8a2b3d4e…)
→ next: share it from its page, or with `adunem harness list`

install

Installs a package harness into your Claude Code and/or Codex. It downloads the bundle, checks its hash, shows you every file in full, and asks before installing anything.

adunem harness install <name> [--client claude-code|codex|both] [--version <v>]
                       [--project] [--yes] [--allow-scripts]

nametextrequired

The package harness, as handle/name.

--clienttextdefault: both

claude-code, codex or both. Only assistants installed on this machine are used.

--versiontextdefault: the latest

A specific version, for example the one your space pins.

--projectflagdefault: off

Install for the current repository only, instead of your whole account.

--yesflagdefault: off

Do not ask to install. Executable files still need --allow-scripts.

--allow-scriptsflagdefault: off

Allow files that can run on your machine, without asking for each one.

What it adds:

  • The instructions become a skill named after the harness, and its skill folders become skills too, in ~/.claude/skills or ~/.codex/skills (with --project, the repository's .claude/skills or .codex/skills). Nothing is added to your CLAUDE.md or AGENTS.md.
  • Its MCP servers are registered with the assistant's own mcp add, started through adunem harness run-mcp so their secrets come from your keychain.
  • Secrets the harness asks for (environment variable names in mcp_servers) are requested once without showing them, or read from that variable, and stored in your operating system's keychain. They are never written to a config file.
  • A managed copy goes in the CLI's config folder, and a lock file records exactly what was written.

Restart open sessions to load it. Already-installed harnesses are refused with a hint to use update.

update

Updates an installed package harness to its latest version, or to --version. It shows the diff of every changed file first, and never overwrites a file you edited without asking.

adunem harness update <name> [--version <v>] [--yes] [--allow-scripts]

nametextrequired

The installed harness, as handle/name or just the name.

--versiontextdefault: the latest

A specific version.

--yesflagdefault: off

Do not ask. It still refuses to overwrite files you edited, and executable files still need --allow-scripts.

--allow-scriptsflagdefault: off

Allow executable files without asking for each one.

If the bundle is the same as what you have, it says <name> is up to date (<version>).

uninstall

Removes exactly what installing added: its skills, MCP entries, managed copy and keychain secrets. Your other settings are untouched.

adunem harness uninstall <name>

Common errors

MessageWhat to do
no single harness called 'x' (matches: ...)Use the full handle/name. adunem harness list shows them.
no adunem-harness.yaml here: run adunem harness initRun the command in a harness folder.
adunem-harness.yaml: tools entry 'x' must be "server/tool" ...Each tools entry needs a server listed under mcp_servers.
the bundle's hash doesn't match the published one: nothing was writtenThe download is not what was published. Nothing was installed. Try again later.
not installed: <file> needs an explicit yes (or --allow-scripts)The bundle includes a file that can run on your machine. Say yes for it, or pass --allow-scripts.
you already have a live harness called 'x'A name is used by one kind only. Rename the folder's harness, or publish as a live one.

On this page