John's Harness

Run a fleet of autonomous coding agents as one cooperative swarm.

John's Harness is a production agent harness for engineers who run more than one coding agent at a time. Agents work the same repositories at once, coordinate through a durable board keyed by git origin, message each other while they run, and ship only through an exact-head push gate with per-commit production authority. Memory persists across sessions and compaction and is shared by every agent in the swarm. Launching a swarm takes one command and a number; the members divide the work among themselves.

Migrating from OpenClaw

Bring your agents, memory, credentials, and scheduled jobs into John's Harness.

npm i -g johns-harness && johnness migrate

Preparation backs up offline state, creates ~/.johnness, rewrites settings, and verifies the result. It does not change services; --force is a nonactivating live-snapshot rehearsal only. On macOS, review attention items, then use johnness migrate --cutover --to ~/.johnness --yes. The detached completer registers a gated native LaunchAgent before stopping the exact selected old job, then requires supervisor, listener PID and HTTP health agreement. Interrupted cutovers resume forward with johnness migrate --resume --to ~/.johnness. Every CLI entrypoint reports an incomplete journal. No service cutover rolls back or deletes the old plist/state. Preview without writes using --dry-run. See migration cutover for ownership requirements, limitations and recovery.

Quick start

Requires Node 22.12 or newer.

npm install -g johns-harness
johnness onboard
johnness memory mk_your_key

The package is johns-harness; the command it installs is johnness.

The wizard sets up credentials, workspace, gateway, and channels. It asks for your MemoryRouter API key and links to signup, free to start. If you skip memory in the wizard, the third line stores the key later.

API spend at a glance

/status shows the last API call's complete new-input, cached-read and output counts, with separate input/read/write/output costs. Anthropic one-hour and five-minute cache writes are priced separately. Tool-heavy turns also show a total across their API calls; /usage cost shows the cumulative session total. See token use and costs.

First run

| Step | Command | What happens | | --- | --- | --- | | Install | npm install -g johns-harness | Installs the CLI, the runtime, and the default memory plugin. A postinstall step applies the patched dependency files. | | Configure | johnness onboard | Interactive wizard for gateway, workspace, and skills. johnness configure reopens it later. | | Memory | johnness memory mk_your_key | Turns on persistent memory. The plugin is already installed and enabled. | | Start | johnness gateway start | Starts the gateway as a background service. johnness gateway run keeps it in the foreground. | | Connect | johnness channels add --channel telegram --token "<bot token>" | Connects a chat channel. Discord, Slack, WhatsApp, Signal, iMessage, Matrix, and more are supported. | | Check | johnness doctor | Health checks and quick fixes for the gateway and channels. |

Signing in from chat

Send /login to list subscription choices. Use /login chatgpt (or /login gpt) for ChatGPT / Codex, and /login claude for a Claude subscription. Provider names are case-insensitive.

For ChatGPT, open the link, sign in, enter the device code on that page and tap Approve. In Telegram, tap the code to copy it. Enable "Device code authorization for Codex" once in chatgpt.com > Settings > Security; then send /login chatgpt for a fresh code. The existing device flow is unchanged.

For Claude, open the link, sign in to your subscription account, approve, then copy the complete code (including #state) from the callback page. Send /login claude <complete code> in the same chat. This uses the Claude Code OAuth client and request envelope, not a new third-party Anthropic client. Eligible Pro, Max and Team accounts use subscription limits first, with your existing Anthropic API-key profile as fallback on rate limits, authentication failures or quota exhaustion. Subscription turns record $0; API fallback turns keep normal API pricing. Tokens refresh automatically. Sign-in does not edit gateway configuration. Subscription turns are served from your plan's included limits: the adapter sends Claude Code's own request attribution (the same first system block and Agent SDK identity line Claude Code sends), so the full harness prompt and tools are not billed as third-party extra usage. If Anthropic ever answers "Third-party apps now draw from extra usage", the harness falls back to the API key on that turn. A login takes effect on the very next turn of every existing session; /status shows the profile that served the last turn.

In a terminal, run johnness login to list choices, johnness login chatgpt or johnness login claude. Claude opens the browser and asks for the complete code; use --no-browser on a remote host to print the link instead. The equivalent commands are johnness models auth login chatgpt and johnness models auth login claude. Existing johnness models auth login --device remains a ChatGPT shortcut.

Batteries included

The harness ships the current model catalog and the short aliases opus, sonnet, fable, astra, sol, luna, terra, gpt, grok, flash, banana, image, deepseek, deepseek-pro, muse, and gemini-lite, so /model opus works on a fresh install with no models.providers block. Channels you configure load without a plugins.allow list; only an explicit enabled: false or plugins.deny turns one off. Updating the harness updates the catalog and aliases for every agent. Any openai-codex/<model> primary that hits its ChatGPT usage limit fails over to openai/<model> on the API key first, then to your configured fallbacks, with no config (the sibling is skipped when no OpenAI API key is present). Image generation and editing go through the image_generate tool. The default chain is subscription only: GPT Image 2.5 Sunburst (openai-codex/gpt-image-2.5-sunburst, alias image) on the ChatGPT subscription, then GPT Image 2 on the subscription (image2); API-key image models are never an implicit fallback, only an explicit model or agents.defaults.imageGenerationModel. Also selectable: GPT Image 2.5 Flare (image-flare), Nano Banana 2.1 (google/gemini-nano-banana-2.1, nano-banana/banana, aspectRatio, imageSize 1K/2K/4K, up to 14 reference images), Nano Banana Pro GA (google/gemini-3-pro-image, nano-banana-pro; the preview stays on nano-banana-pro-preview), Nano Banana 2 Lite (nano-banana-lite, 1K only) and xAI Grok Imagine Image 2.0 (grok-image, native xAI JSON generation and editing). GPT Image 2.5 adds quality xhigh/max and custom sizes; per-model rules come from models/models.json.

The alias contract. Every shipped alias points at the newest model in its line, so an install or an /update moves every agent forward with zero per-instance config. Your own agents.defaults.models[*].alias entries are still consulted first and still win. Every catalog bump must move the matching alias; the verifier fails the release if it does not. /model deepseek always selects the newest DeepSeek model (currently V4.1 Flash); deepseek-pro the newest Pro.

Updating from chat

Send /update to install the newest johns-harness on the machine the gateway runs on and restart into it; /update 2026.9.14 pins an exact version. Owner only. The reply names the current and target versions, a second /update while one is running is refused, and the first message after the restart confirms the running version. On a writable host the package is reinstalled into the existing global prefix. On an immutable image with a persistent volume (Fly), it is installed into $JOHNNESS_STATE_DIR/runtime/johnness and the entrypoint prefers that runtime when it is newer than the image: exec node "$(node /opt/johnness/lib/node_modules/johns-harness/dist/runtime-path.js)" gateway run. JOHNNESS_UPDATE_PREFIX overrides the target. On failure the reply carries the last lines of npm output and the one command that fixes it.

Optional local engines

The default install stays lean. Remote embeddings, hosted PDF understanding, chat, channels, tools, memory, and swarms do not need local embedding or PDF engines. Opt in when you use local extraction:

npm i -g node-llama-cpp   # local embeddings
npm i -g [email protected] @napi-rs/[email protected] [email protected]  # local PDF text and images
npm i -g koffi            # Windows enhanced terminal input only

Use the same npm prefix as johns-harness (add the same --prefix /path to those commands). Missing local engines return the install command, not a startup failure. pdf-parse is pinned to its callable v1 API used by memory uploads. Production dependency source maps are removed after install; set JOHNNESS_KEEP_SOURCEMAPS=1 during installation to keep dependency maps for debugging. No --omit=optional or --omit=peer flag is needed for the slim default.

From source

git clone https://github.com/John-Rood/johns-harness.git
cd johns-harness && npm install
node johnness.mjs --help

Verify

npm test                        # 992 tests against the installed dependency tree
bash scripts/verify-patches.sh  # 468 checks across every patch family

Launch a swarm with one command

One call, one number. The orchestrator writes a single directive and chooses how many agents should work it. The members decide everything else.

swarm_spawn({
  directive: "<the whole briefing: goal, scope, forbidden files, push rules, author identity>",
  count: 12,
  coord: { root: "/abs/path/to/repo", branch: "main", prodAuthorized: false },
  model: "anthropic/claude-fable-5-1"      // optional, applies to every member
})

Every member receives the same directive plus a short runtime preamble that carries the protocol. Nobody hands out work.

The lowest-numbered live member decomposes the directive into work items on the shared board. The post is a compare-and-swap, so exactly one plan exists no matter how many members arrive at the same moment; the rest wait for it rather than poll.

Each member claims one open item atomically, works it, pushes, marks it done or failed, and claims the next. A claim is exactly one winner, even under concurrent attempts.

Claims carry a 15 minute lease that heartbeats extend. A lease that lapses reopens the item the moment anyone looks at the board, so a dead member never strands its work.

When work reveals more items, any member appends them to the plan and the addition wakes the others through their inboxes. Members message each other directly only for a real dependency, and each records how the swarm coordinated so the next one starts smarter.

The preamble also carries the operating protocol as defaults with named exceptions: the planner declares the shape of the work, one integrator merges parallel branches and builds and pushes once so parallel work flows into a single sequential step, one gateway or a shared budget fronts each rate-limited host, and done means done. Members ask a service holder with a durable request and wait on the answer without polling.

Per-member announces are suppressed. When the last member finishes, one swarm finished rollup arrives with every item, its owner, its pushed head, and its summary.

count runs from 2 to 100. Members beyond the concurrency limit are queued and start as slots free, and swarm_status reads a swarm's progress without interrupting anyone. Members are ordinary agents: same depth rules, same push preflight, same per-commit production authority, no force pushes.

Full guide, including the preamble members receive and the work item state machine: docs/SWARM.md.

The problem

Coding agents today run as isolated processes. Two agents on the same repository have no shared state, no way to talk to each other mid-task, and no gate between a dirty local branch and production. Once a context window compacts, whatever the agent knew is gone.

What makes it different

• A swarm, not a pile of agents. One coordination board per repository, direct agent-to-agent messages delivered inside a busy agent's run, exclusive claims on shared areas, a push preflight that blocks stale, forced, broad, and unauthorized pushes, and swarm_spawn, which launches up to 100 agents from one directive in a single call.
• Memory built for production. Tiered recall that traces from consolidated reflections down to the verbatim record, surviving compaction and shared across the swarm. Installed and enabled by default.
• Production authority per commit. Promotion is granted to an exact SHA, never to a branch name, so one worker's authorization never covers another worker's commits.
• An append-only action log. Agents record every consequential action to ACTION_LOG.md and read it before acting.
• A fixed runtime surface. The core does not grow on a schedule. New mechanisms enter only to solve a demonstrated production failure, one narrow, tested, reversible patch at a time: 76 patch families, each with a regression test and an explicit recovery path.
• Reliability with a definition. Bounded retries, explicit failure states, exact-once continuation, context-pressure recovery, durable delivery, and supervised gateway recovery.
• Coding first, phone optional. Direct the work at a high level from a chat channel while agents plan, implement, test, coordinate, and stage releases unattended.
• Local voice. Optional native Whisper transcription of inbound audio, entirely on your machine. Off by default. Setup.

How it works

Agents talk to each other laterally, not through the orchestrator. Every clone of a repository lands on the same board, and memory sits beside the swarm as shared infrastructure.

| Stage | Mechanism | Guarantee | | --- | --- | --- | | 1. Spawn | The orchestrator starts agents with repo, branch, areas, and prodAuthorized attached, then steps back. | Work is divided once; the orchestrator is not a traffic hub. | | 2. Claim | Each agent takes an exclusive claim on the areas it will touch, recorded on a board keyed by normalized git origin. | Two agents never silently edit the same surface. | | 3. Work | Agents post progress, exact heads, and pushed or blocked state to the board as they go. | The record outlives a busy or departed sibling. | | 4. Message | A message to a busy sibling is delivered between tool steps, in its active run, with no restart. Receipts read queued, delivered, or replied. | Late instructions land before the run finishes, through a sealed pre-completion drain. | | 5. Push gate | Preflight compares the exact local head against a freshly fetched remote before any push. | Stale, forced, broad, and unauthorized pushes are blocked; a sibling's published head is integrated, never overwritten. | | 6. Production | Promotion is authorized per exact commit SHA. | Authorization to ship one change never covers commits riding along with it. |

Swarm

Agents sharing a filesystem are not a swarm. A swarm knows who owns which work, exchanges instructions while the work is in flight, and reconciles changes before anything is pushed. John's Harness puts that coordination in the runtime, not in a prompt.

One board per repository. The board is durable and keyed by normalized git origin. It records claims, progress, exact heads, pushed and blocked work, production authority, and messages.

Messages land inside the active run. Siblings message each other directly, scoped to the repository, with no reach into unrelated sessions. Waiting is reported as waiting, never as a timeout.

Every push clears a gate. The preflight blocks stale pushes, force pushes, broad pushes, and pushes that carry another worker's unauthorized commits.

Production authority belongs to a commit. Never to a branch name or a timestamp.

One directive, one number. swarm_spawn launches up to 100 members from the same briefing and they divide the work themselves. See the launch section near the top of this page and the swarm guide.

Memory

Run johnness memory mk_your_key to set your MemoryRouter API key and start persistent memory, or enter it during onboarding.

The future of AI is not smarter models. It is models with the right context: what is happening, what happened before, and what matters now.

An agent in this harness remembers what it was told yesterday, the decision it made last Tuesday, the fix it tried that did not work, and why. That context persists across sessions and survives compaction. It does not live and die inside one context window.

| Capability | How it works | | --- | --- | | Tiered, traceable recall | Raw verbatim memories at the bottom, reflections of specific events above them, consolidated reflections on top. Any high-level memory drills back to its exact source. | | Time-window and semantic recall | "What happened last week" and "find the decision about X" both work. | | Reflect, then commit | Consolidation checks out a batch, writes reflections, and changes nothing until commit. Memory is never silently rewritten. | | Shared across the swarm | Every agent reads from the same memory. Context one agent earned is available to the next. |

The implementation is mr-memory, installed and enabled as the default memory plugin. The one requirement is a MemoryRouter API key from memoryrouter.ai. Behind the key is an effectively infinite memory space, sharded across distributed A100s on cloud edge compute: years of memory, added to every day, available in an instant.

Action log

Agents append every consequential action to ACTION_LOG.md at the workspace root and read it before acting. What shipped, what was sent, and what changed stays on disk for the next decision, in this session or the next.

The log is a RULES.md workspace convention enforced through the activity-logging skill and paired with the daily log. It records outcomes, not busywork.

Design principles

Simplicity by design. Fewer features, fewer failure surfaces. The core is fixed and does not take on features for their own sake; a mechanism is added only to solve a demonstrated problem, and every addition is narrow, tested, documented, and independently reversible. A runtime that changes only when production demands it is a runtime you can reason about at 3 a.m.

Reliability and durability. Bounded retries, explicit failure states, exact-once continuation, context-pressure recovery, durable delivery, supervised gateway recovery, and tests that run against the package and its installed dependencies.

Coding first. The harness works as a companion, but it is built for autonomous coding: plan, inspect repositories, implement, test, coordinate with peers, stage through staging-first git, and ship through pipeline-only deployment paths. The step beyond a single coding session is an engineering operation that keeps working while you are away from the keyboard.

Patch families

The runtime carries 76 patch families plus the 65.1 safe-update amendment. Each is a production fix applied at the source with a regression test, a durable patch marker, and an explicit recovery path. A verifier runs 468 checks against the package tree and installed dependencies, and 992 tests run against the installed dependency tree.

Every family follows the same six steps: reproduce the failure, trace the exact runtime path, make the smallest source-level change that restores the invariant, add a regression test and a patch marker, run the verifier, and retain rollback artifacts. The full index: docs/PATCHES.md.

Configuration

| Item | Detail | | --- | --- | | Node | >=22.12.0 (from package.json engines) | | State directory | ~/.johnness holds config, credentials, sessions, and the workspace | | --profile <name> | Isolates state under ~/.johnness-<name> so several installs coexist on one machine | | --dev | Dev profile under ~/.johnness-dev with its own gateway port and shifted derived ports | | Rules | RULES.md ships 19 operating-policy sections injected on every call. Fill in the placeholders; keep long procedures in skills. | | Orchestrator skill | Bundled and loaded implicitly on every install. Decide whether to pass the user's words through or expand them, then keep the briefing brief. Override with a workspace skills/orchestrator/SKILL.md. | | Bundled generic skills | Eight generic skills ship in skills/ and load by description match: code-ops, web-research, plan-archival, todos, arch-viz, gcp-logs, activity-logging, outlook. Workspace copies override; enabled: false and allowBundled still apply. |

Documentation

• docs/index.md: runtime docs, from gateway and channels to plugins, nodes, and CLI reference.
• docs/PATCHES.md: the 76 patch families, one record each.
• docs/NATIVE-WHISPER-MUSE.md: local Whisper transcription setup.
• RULES.md: the default operating rules, including Rule Zero on production authorization.

Contributing

Issues and pull requests are welcome. Run npm test and bash scripts/verify-patches.sh before opening a PR. One narrow, tested, reversible patch per change; fixes come with a regression test and a rollback path.

License

MIT. See LICENSE.