Local control plane for bring-your-own coding agents.

A local-first shared handoff, supervision, and ops layer for Claude Code, Hermes, OpenClaw, and other terminal agents.

agentcodehandoff gives multiple coding agents one coordination layer inside a shared repo: clear handoffs, explicit ownership, supervised bridge processes, workflow-state updates, and a durable local record of who is doing what.

It is intentionally a coordination layer, not a hosted model provider. You bring your own installed and configured agent tools. AgentCodeHandoff handles the collaboration.

Try This Now

./install.sh
agentcodehandoff quickstart --repo /path/to/repo
agentcodehandoff dashboard --view ops --interactive

Then send one real request:

agentcodehandoff request \
  --from-agent claude \
  --to-agent hermes \
  --summary "Need help" \
  --details "Reply automatically with a short acknowledgement." \
  --files README.md

Choose your team:

• local-trio: Hermes + Claude + OpenClaw
• local-squad: Hermes + Claude + OpenClaw
• local-pair: Hermes + Claude

If you want the four-agent setup:

agentcodehandoff quickstart --template local-squad --repo /path/to/repo

Common first-run fixes:

• agentcodehandoff doctor if a bridge will not start. It now prints agent-specific next steps for missing or unauthenticated CLIs.
• agentcodehandoff doctor also runs deeper runtime checks for Claude auth and Hermes provider reachability before you start bridges.
• agentcodehandoff agent-check --agent claude --repo /path/to/repo if claude auth status looks healthy but the supervised Claude bridge still fails.
• agentcodehandoff agent-check --agent hermes --repo /path/to/repo if Hermes is installed but timing out or not reaching its configured provider.
• agentcodehandoff bridge-status if a bridge looks paused or stale. It now prints a remediation hint alongside the failure class and last error.
• agentcodehandoff logs --agents claude --lines 40 if Claude is installed but not replying
• agentcodehandoff logs --agents openclaw --lines 40 if OpenClaw is installed but not configured

Recovery

If quickstart or up --template local-trio does not get you to a healthy trio, run the agent-specific checks directly:

agentcodehandoff agent-check --agent claude --repo /path/to/repo
agentcodehandoff agent-check --agent hermes --repo /path/to/repo

What they tell you:

• claude: checks the real bridge invocation path and catches the common mismatch where claude auth status in one shell looks fine but the supervised bridge runtime is not actually logged in
• hermes: shows whether Hermes can reach its configured provider path and, on failure, reports the provider, model, and endpoint that timed out

If either one fails, fix that agent first and rerun:

agentcodehandoff quickstart --template local-trio --repo /path/to/repo

For a concrete end-to-end example with real Claude and Hermes failure outputs, see examples/recovery.md. For the four-agent setup, see examples/local-squad-recovery.md.

Affected By The Claude Harness Policy?

If you still want Claude Code in the mix, but cannot rely on a third-party harness model anymore, this is the intended setup:

• run your own installed claude CLI
• run your own configured hermes and optionally openclaw agent runtimes
• let AgentCodeHandoff coordinate them in your environment

Start here:

agentcodehandoff quickstart --template local-trio --repo /path/to/repo

If Claude still fails even though claude auth status looks fine:

agentcodehandoff agent-check --agent claude --repo /path/to/repo

That reproduces the real bridge invocation path and tells you exactly what to fix next.

If you are using the four-agent squad, also run:

agentcodehandoff agent-check --agent openclaw --repo /path/to/repo

and use examples/local-squad-recovery.md as the recovery checklist.

It is built for teams running:

• Claude + Hermes
• Claude + Hermes + OpenClaw
• two or more agent terminals on one machine
• one shared codebase
• a zero-infrastructure workflow

It now supports:

• 3-agent supervised team startup with local-trio
• 4-agent supervised team startup with local-squad
• availability-aware routing and graceful fallback when one agent is rate-limited or offline
• interactive terminal ops for recovery, sweeping, and request resolution
• live-verified Claude bridge replies via structured JSON output

Why Teams Need It

Most multi-agent coding workflows break on coordination, not model quality:

• no durable handoff stream
• no clear ownership of files or scopes
• no quick way to see who is doing what
• no shared notion of blocked, done, or review-ready work
• too much manual relaying between terminals

agentcodehandoff fixes that with a small, explicit local state model:

• ~/.agentcodehandoff/inbox.jsonl
• ~/.agentcodehandoff/claims.json

What This Is

• A local-first coordination layer for Claude Code, Hermes, OpenClaw, and similar terminal agents
• A shared handoff, routing, supervision, and recovery system that runs on your machine
• A way to make already-installed agents collaborate inside one repo without constant human relaying

What This Is Not

• Not a hosted agent platform
• Not a model provider
• Not a third-party Claude subscription harness
• Not a resale layer for API or subscription access

Authentication Model

AgentCodeHandoff follows a bring-your-own-agent model:

• for subscription-backed tools like claude, you use your own installed and authenticated CLI in your environment
• for harness-style tools like hermes and openclaw, you use your own configured runtimes, providers, and local setup
• AgentCodeHandoff launches and coordinates those tools; it does not provide the underlying subscriptions, providers, or models

This repo is designed for orchestration of user-controlled agent runtimes. It is not designed to proxy or resell third-party subscription access through a hosted service.

What It Includes

• Shared inbox for agent-to-agent handoffs
• Lightweight claim board for file and scope ownership
• Availability-aware routing across Hermes, Claude, and OpenClaw
• Workflow updates for request, done, blocked, and review
• Request lifecycle tracking with acknowledged, done, blocked, review, closed, approved, and escalated
• Claim resolution with final states like completed, blocked, and abandoned
• Git worktree-backed agent sessions for isolated edit space
• File-awareness checks that compare live session edits to claimed files
• Drift suggestions and safe remediation for expand, handoff, and split-work flows
• Supervised bridge lifecycle commands with pid, heartbeat, and pending request visibility
• Saved bridge profiles, reusable presets, and one-command team lifecycle controls
• Automatic timeout recovery with reminders, reroutes, and escalation when safe recovery is exhausted
• Terminal-first workflow for two or more agents in one repo
• Paneled terminal dashboard for bridge health, workflow, requests, claims, conflicts, and recent messages
• Interactive ops dashboard with direct recovery and request-resolution shortcuts
• Local-first state with no daemon required
• Agent-specific wrapper commands for faster day-to-day use

Current State

This repo is no longer just a shared inbox prototype. The current build supports:

• local pair and local trio presets
• local squad preset with OpenClaw support
• supervised up / down / restart-team lifecycle commands
• persistent bridge recovery profiles
• interactive operator controls from the terminal dashboard
• explicit availability overrides for rate-limited or offline agents
• live trio verification with Hermes, Claude, and OpenClaw

First 5 Minutes

If you want the fastest path from clone to real collaboration, use the golden path:

agentcodehandoff quickstart --repo /path/to/repo

That will:

• initialize local state
• install wrappers
• run setup checks
• start the default supervised local trio
• print the next commands to use

Then open the operator view:

agentcodehandoff dashboard --view ops --interactive

And send one real request:

agentcodehandoff request \
  --from-agent claude \
  --to-agent hermes \
  --summary "Need help" \
  --details "Reply automatically with a short acknowledgement." \
  --files README.md

Guided examples:

• First 5 Minutes
• Supervised Bridge Workflow
• Local Squad Workflow

Public Alpha Verification

The current build has been verified against the real local toolchain, not just isolated tests.

Live verification completed with:

• agentcodehandoff up --template local-trio
• real supervised bridges for Hermes and Claude
• real requests sent through AgentCodeHandoff into the shared inbox
• real automatic replies written back by Hermes and Claude

Observed live replies:

• hermes -> claude
  • Acknowledged public release verification
• claude -> hermes
  • ACK: Public release live verification task received

That confirms the public-alpha story is accurate: this tool can bring up a real local trio, coordinate requests, and receive actual bridge-written replies through the shared collaboration layer.

OpenClaw is now supported as a first-class agent in the tool, including wrappers, routing, supervision, and presets. Live OpenClaw replies still depend on OpenClaw's own gateway and agent configuration in the local runtime.

Positioning

The product story is intentionally simple:

• you already have agent tools
• you already pay for them however you choose
• AgentCodeHandoff makes them coordinate

That keeps the tool lightweight, local, and practical for real engineering workflows.

FAQ

Is this a hosted harness for Claude or other agent subscriptions?

No. AgentCodeHandoff is a coordination layer. You run your own installed agent tools and keep auth or provider setup in those tools. AgentCodeHandoff coordinates them.

Is this useful if I am affected by stricter Claude policy around third-party harnesses?

Yes. The intended model is not "Claude runs everything for you through a third-party service." The intended model is "Claude Code is one installed agent tool in a team, and AgentCodeHandoff coordinates it with Hermes, OpenClaw, or other agent tools in your environment."

Does OpenClaw work here?

Yes, OpenClaw is now a first-class supported agent in the tool. It is included in routing, wrappers, supervision, and the built-in local-squad preset. Live replies still depend on OpenClaw itself being configured locally.

Do I need to pay API costs through AgentCodeHandoff?

No. This is a bring-your-own-agent tool. You use whatever installed CLIs, harnesses, plans, or providers you already use. AgentCodeHandoff is the coordination layer, not the provider.

What is the fastest way to see it working?

Run:

./install.sh
agentcodehandoff quickstart --repo /path/to/repo
agentcodehandoff dashboard --view ops --interactive

Architecture

Quick Start

cd agent-inbox
./install.sh

That installs the CLI, creates the local state directory, seeds bootstrap messages, and installs helper wrappers under ~/.local/bin.

Try a disposable end-to-end demo:

./examples/demo-session.sh

For the full supervised collaboration path, start with:

1. agentcodehandoff doctor
2. agentcodehandoff up --template local-trio --repo /path/to/repo
3. agentcodehandoff dashboard --view ops --interactive
4. agentcodehandoff bridge-status
5. agentcodehandoff requests
6. agentcodehandoff availability

If you are the second collaborator terminal, keep this shorter loop:

1. agentcodehandoff-hermes-watch
2. agentcodehandoff dashboard --view ops
3. agentcodehandoff bridge-status
4. agentcodehandoff bridge-profile-show --agent hermes

First Run

agentcodehandoff doctor
agentcodehandoff status

For a read-only observer setup, start two terminals:

agentcodehandoff-hermes-watch
agentcodehandoff-claude-watch

For manually managed auto-reply bridges, start them in real terminals:

agentcodehandoff-hermes-auto --repo /Users/iris/Projects/agent-inbox
agentcodehandoff-claude-auto --repo /Users/iris/Projects/agent-inbox
agentcodehandoff-openclaw-auto --repo /Users/iris/Projects/agent-inbox

Enable automatic file claims from bridge replies:

agentcodehandoff-hermes-auto --repo /Users/iris/Projects/agent-inbox --claim-on-files

Check whether the bridges appear alive:

agentcodehandoff auto-status

Override an agent's availability when you already know it is offline or rate-limited:

agentcodehandoff availability-set --agent claude --state rate-limited --note "subscription window exhausted"
agentcodehandoff availability

For day-to-day supervised operation, prefer managed background bridges instead of keeping separate reply terminals open:

agentcodehandoff bridge-start --agent hermes --repo /path/to/repo --auto-sweep
agentcodehandoff bridge-start --agent claude --repo /path/to/repo --auto-sweep
agentcodehandoff bridge-start --agent openclaw --repo /path/to/repo --auto-sweep

Or apply the built-in trio preset in one step:

agentcodehandoff bridge-preset-apply --name local-trio --repo /path/to/repo --start

Or bring up the built-in four-agent preset:

agentcodehandoff bridge-preset-apply --name local-squad --repo /path/to/repo --start

Or use the higher-level team lifecycle commands:

agentcodehandoff up --template local-trio --repo /path/to/repo
agentcodehandoff up --template local-squad --repo /path/to/repo
agentcodehandoff down --template local-trio --repo /path/to/repo
agentcodehandoff restart-team --template local-trio --repo /path/to/repo

The local-trio flow has been live-verified with Hermes, Claude, and OpenClaw replying through supervised bridges.

Visuals

Primary assets in this repo:

• brand mark: assets/agentcodehandoff-mark.svg
• README lockup: assets/agentcodehandoff-lockup.svg
• social preview: assets/agentcodehandoff-social-preview.svg

For GitHub repo presentation, use assets/agentcodehandoff-social-preview.svg as the social preview image.

For live terminal operations, enable dashboard actions:

agentcodehandoff dashboard --view ops --interactive

Keys:

• a apply the top safe ops action
• r recover bridges
• s sweep stale requests
• p approve the top actionable request resolution
• c close the top actionable request resolution
• e escalate the top actionable request resolution
• q quit

Inspect supervised bridge health:

agentcodehandoff events --limit 20
agentcodehandoff request-trace --request-id <request-id>
agentcodehandoff ps
agentcodehandoff bridge-status
agentcodehandoff logs --agents claude --lines 40
agentcodehandoff bridge-profiles
agentcodehandoff bridge-presets

Open the live terminal dashboard. Use the default view for coordination and the ops view for bridge supervision, stale requests, and recovery visibility:

agentcodehandoff-dashboard
agentcodehandoff dashboard --view ops
agentcodehandoff ops-next

Send a handoff:

agentcodehandoff-claude-send \
  --summary "Need a realism pass" \
  --details "Own MeshGraph.tsx only" \
  --files "frontend/src/components/MeshGraph.tsx"

Send an auto-reply request:

agentcodehandoff-claude-request \
  --summary "Need a quick review" \
  --details "Reply automatically with short feedback." \
  --files "README.md"

Route a request automatically:

agentcodehandoff dispatch \
  --from-agent claude \
  --summary "Fix failing CLI test" \
  --details "Investigate the parser behavior and send it to the best agent automatically." \
  --files "src/agentcodehandoff/cli.py,README.md"

Claim a scope:

agentcodehandoff-hermes-claim \
  --scope meshgraph-pass \
  --summary "Owning cinematic sphere polish" \
  --files "frontend/src/components/MeshGraph.tsx"

Send a completion update:

agentcodehandoff-claude-done \
  --summary "CLI workflow states shipped" \
  --details "done, blocked, review, and claim resolution are live." \
  --files "src/agentcodehandoff/cli.py,README.md"

Signal a blocker:

agentcodehandoff-hermes-blocked \
  --summary "Need routing policy input" \
  --details "Current heuristics are too generic for design-vs-code review tasks." \
  --files "src/agentcodehandoff/cli.py"

Request review:

agentcodehandoff-claude-review \
  --summary "Review the dispatch heuristics" \
  --details "Check whether docs-heavy mixed tasks should route to Hermes." \
  --files "src/agentcodehandoff/cli.py,README.md"

Resolve a claim:

agentcodehandoff resolve \
  --agent claude \
  --scope cli-workflow-pass \
  --status completed \
  --note "Merged and verified locally."

Start an isolated worktree session:

agentcodehandoff session-start \
  --agent claude \
  --scope parser-pass \
  --repo /path/to/repo \
  --note "Isolated parser refactor worktree"

List sessions:

agentcodehandoff sessions

Close a session and remove its worktree:

agentcodehandoff session-end \
  --agent claude \
  --scope parser-pass \
  --note "Merged and cleaned up"

Inspect live drift against claimed files:

agentcodehandoff drift

Get actionable scope suggestions:

agentcodehandoff suggest

Inspect request lifecycle state:

agentcodehandoff requests

Resolve a tracked request explicitly:

agentcodehandoff request-resolve --request-id msg-123 --action approve
agentcodehandoff request-resolve --request-id msg-123 --action close

Sweep stale requests and apply timeout actions:

agentcodehandoff request-sweep

Let supervised bridges recover their own stale requests automatically:

agentcodehandoff bridge-start --agent hermes --repo /path/to/repo --auto-sweep --sweep-interval 30 --max-restarts 5

Recover paused or down bridges with one command:

agentcodehandoff bridge-recover

Bridge recovery uses the last saved per-agent profile even after a full stop removes the live lock.

Recommended Onboarding For Claude + Hermes

This is the clearest path for two-agent collaboration in one shared repo.

1. Install and verify local state.

./install.sh
agentcodehandoff doctor

2. Start supervised bridges for each agent that should auto-reply.

agentcodehandoff bridge-start --agent hermes --repo /path/to/repo --auto-sweep
agentcodehandoff bridge-start --agent claude --repo /path/to/repo --auto-sweep

3. Keep one terminal on the ops dashboard.

agentcodehandoff dashboard --view ops

4. In active agent terminals, use claims plus request, done, blocked, and review updates.

5. If a bridge stops responding, inspect it first:

agentcodehandoff bridge-status
agentcodehandoff requests
agentcodehandoff request-sweep

6. If the bridge is down or paused, recover it using the saved profile:

agentcodehandoff bridge-recover

7. If recovery is exhausted, fall back to manual auto terminals:

agentcodehandoff-hermes-auto --repo /path/to/repo
agentcodehandoff-claude-auto --repo /path/to/repo

This gives a clean split:

• supervised bridges for normal unattended routing
• ops dashboard for health and stale-request visibility
• manual auto terminals as a safe fallback during bring-up or debugging

Supervised Bridge Workflow

Use this when you want the tool to keep automation alive without manual babysitting.

Start bridges:

agentcodehandoff bridge-start --agent hermes --repo /path/to/repo --auto-sweep
agentcodehandoff bridge-start --agent claude --repo /path/to/repo --auto-sweep

Inspect health:

agentcodehandoff bridge-status
agentcodehandoff dashboard --view ops

Common checks:

• bridge-status for pid, heartbeat, pending requests, restart counts, and saved profile timestamps
• dashboard --view ops for at-a-glance bridge state, stale requests, and remediation context
• requests and request-sweep when work is stuck but the bridge still appears alive

Stop or restart a specific bridge:

agentcodehandoff bridge-stop --agent hermes
agentcodehandoff bridge-restart --agent hermes --repo /path/to/repo

Profile Recovery Workflow

Supervised bridges persist a per-agent profile so recovery does not depend on a live lock file surviving.

Typical recovery loop:

1. A bridge is down, paused, or missing after a shell restart.
2. agentcodehandoff bridge-status shows no healthy live process, but still shows the saved repo profile.
3. agentcodehandoff bridge-recover restarts the bridge using the last saved settings.
4. agentcodehandoff dashboard --view ops confirms heartbeat and pending request state.

Example:

agentcodehandoff bridge-status
agentcodehandoff bridge-recover
agentcodehandoff bridge-status

Use bridge-recover --fail-if-idle in scripts when you want a non-zero exit if nothing actually needed recovery.

Inspect or delete a saved bridge profile:

agentcodehandoff bridge-profile-show --agent hermes
agentcodehandoff bridge-profile-delete --agent hermes

Save reusable bridge presets and apply them later:

agentcodehandoff bridge-preset-save --name local-pair --agents hermes claude
agentcodehandoff bridge-preset-apply --name local-pair --start

Ask the tool for the single most important next ops action:

agentcodehandoff ops-next
agentcodehandoff ops-next --apply
agentcodehandoff ops-next --apply --create-session

Apply a safe remediation automatically:

agentcodehandoff remediate --agent claude --scope parser-pass

Create a new split scope and session when drift becomes separate work:

agentcodehandoff remediate --agent claude --scope parser-pass --create-session

Core Commands

agentcodehandoff init --install-wrappers --seed
agentcodehandoff doctor
agentcodehandoff read --agent claude
agentcodehandoff watch --agent hermes
agentcodehandoff latest --agent hermes
agentcodehandoff events
agentcodehandoff request-trace --request-id <request-id>
agentcodehandoff status
agentcodehandoff auto-status
agentcodehandoff dashboard
agentcodehandoff-dashboard
agentcodehandoff-status
agentcodehandoff claims
agentcodehandoff sessions
agentcodehandoff drift
agentcodehandoff suggest
agentcodehandoff requests
agentcodehandoff request-sweep
agentcodehandoff remediate --agent claude --scope parser-pass
agentcodehandoff bridge-status
agentcodehandoff resolve --agent claude --scope cli-pass --status completed

Demo

examples/demo-session.sh runs a safe local session in /tmp:

• initializes state
• creates wrappers
• records a claim
• sends a request-style handoff
• prints status
• prints the next supervised bridge and ops commands to try in a real repo

Testing

Run the current critical-path test suite with:

python3 -m unittest discover -s tests -v

The current suite covers:

• init and doctor against isolated fake Hermes, Claude, and OpenClaw CLIs
• availability overrides and routing fallback
• bridge preset persistence for local-trio
• bridge preset persistence for local-squad
• bridge startup validation for missing agent CLIs and non-git repos
• stale lock cleanup and paused-bridge recovery from saved profiles
• restart-cap pause behavior for supervised bridges
• merged bridge/message timeline via events
• per-request lifecycle trace via request-trace
• per-agent bridge log access
• compact per-agent team summaries with ps
• supervised local-trio startup plus an actual Claude bridge reply in an isolated temp repo
• supervised local-squad startup with OpenClaw included in the team health path
• tracked request resolution
• golden-path quickstart onboarding

This is the current release-hardening baseline. Before a broad public release, the suite should continue to grow around deeper drift/remediation flows and additional long-running provider/runtime behaviors.

Known Limitations

• Agent bridge behavior still depends on the local Claude and Hermes CLIs being installed and authenticated in the environment that launches the bridge.
• Public users should still expect local runtime/environment differences across agent CLIs, but bridge-start now fails early for invalid repos and missing agent CLIs instead of deferring that failure to a background process.
• Real provider/runtime differences can still surface outside the isolated fake-agent test suite.
• The dashboard is terminal-first and intentionally lightweight; it is not a full graphical control plane.
• The current test suite is strong on critical paths, but not yet exhaustive across every command combination.
• Claude Code behavior depends on the local claude CLI being installed and authenticated in the same runtime environment where the bridge process is launched.

Wrapper Commands

Installed by agentcodehandoff init --install-wrappers:

• agentcodehandoff-dashboard
• agentcodehandoff-auto-status
• agentcodehandoff-events
• agentcodehandoff-request-trace
• agentcodehandoff-status
• agentcodehandoff-sessions
• agentcodehandoff-drift
• agentcodehandoff-suggest
• agentcodehandoff-requests
• agentcodehandoff-request-sweep
• agentcodehandoff-remediate
• agentcodehandoff-availability
• agentcodehandoff-availability-set
• agentcodehandoff-quickstart
• agentcodehandoff-up
• agentcodehandoff-down
• agentcodehandoff-restart-team
• agentcodehandoff-bridge-status
• agentcodehandoff-hermes-watch
• agentcodehandoff-claude-watch
• agentcodehandoff-openclaw-watch
• agentcodehandoff-hermes-read
• agentcodehandoff-claude-read
• agentcodehandoff-openclaw-read
• agentcodehandoff-hermes-auto
• agentcodehandoff-claude-auto
• agentcodehandoff-openclaw-auto
• agentcodehandoff-hermes-send
• agentcodehandoff-claude-send
• agentcodehandoff-openclaw-send
• agentcodehandoff-hermes-request
• agentcodehandoff-claude-request
• agentcodehandoff-openclaw-request
• agentcodehandoff-hermes-claim
• agentcodehandoff-claude-claim
• agentcodehandoff-openclaw-claim
• agentcodehandoff-hermes-done
• agentcodehandoff-claude-done
• agentcodehandoff-openclaw-done
• agentcodehandoff-hermes-blocked
• agentcodehandoff-claude-blocked
• agentcodehandoff-openclaw-blocked
• agentcodehandoff-hermes-review
• agentcodehandoff-claude-review
• agentcodehandoff-openclaw-review
• agentcodehandoff-hermes-release
• agentcodehandoff-claude-release
• agentcodehandoff-openclaw-release

Typical Workflow

1. Agent A claims a bounded scope.
2. Agent B claims a non-overlapping scope.
3. Both agents keep watch or dashboard running.
4. Use request for work that expects a response.
5. Use done, blocked, or review so progress reads like a workflow, not raw chat.
6. Resolve claims with completed, blocked, or abandoned when work closes out.
7. Use agentcodehandoff status to inspect latest handoffs, workflow events, open claims, and recently resolved claims.

Terminal Dashboard

agentcodehandoff-dashboard is the fastest way to understand live system state in one terminal.

It shows:

• bridge health for Hermes, Claude, and OpenClaw
• latest handoffs
• workflow events like request, blocked, review, and done
• open claims
• claim conflicts
• recently resolved claims
• recent message traffic
• active worktree sessions
• file-awareness drift summaries
• actionable suggestions for expand, split, or handoff decisions
• safe remediation helpers for claim expansion and handoff generation
• split-work remediation that can create a new claim and optional session
• request lifecycle tracking with pending, acknowledged, stale, and outcome states
• stale-request sweep for reminders and reroutes

Worktree Sessions

agentcodehandoff can manage isolated git worktrees per agent and scope.

Use this when you want:

• one agent per branch/worktree
• clean physical separation of edits
• session state that matches claim state
• dashboard visibility into who owns which workspace

By default, sessions create worktrees under:

• <repo>/.worktrees/<agent>-<scope-slug>

Default branch naming:

• ach/<agent>/<scope-slug>

Core commands:

agentcodehandoff session-start --agent claude --scope parser-pass --repo /path/to/repo
agentcodehandoff sessions
agentcodehandoff drift
agentcodehandoff suggest
agentcodehandoff session-end --agent claude --scope parser-pass

Auto Reply

agentcodehandoff auto --agent <name> watches the inbox and uses a local agent CLI to generate a JSON reply automatically.

• hermes uses hermes chat -Q -q
• claude uses claude -p
• openclaw uses openclaw agent --json --agent main

Example:

agentcodehandoff-hermes-auto --repo /Users/iris/Projects/agent-inbox
agentcodehandoff-claude-auto --repo /Users/iris/Projects/agent-inbox
agentcodehandoff auto-status

Auto-claim example:

agentcodehandoff-hermes-auto \
  --repo /Users/iris/Projects/agent-inbox \
  --claim-on-files

Notes:

• claude requires a valid Claude Code CLI login in the shell environment where the bridge runs.

• openclaw requires OpenClaw itself to be configured well enough for openclaw agent --json --agent main to complete in the local runtime where the bridge runs.

• smart routing automatically deprioritizes agents with auth, rate-limit, or paused bridge failures when supervision state is available.

• this works only in a real terminal environment where Hermes and Claude can reach their providers

• it is not expected to work inside a restricted offline sandbox

• the auto bridge only replies to messages addressed to that agent

• auto bridges only respond to request, task, and auto-request roles

• plain handoff messages are informational and do not auto-trigger replies

Bridge Supervision

Supervised bridges let the tool keep automation running without constant manual babysitting.

What supervision adds:

• one managed background bridge per agent
• pid and heartbeat tracking
• pending request visibility
• log file paths for bridge output
• restart counts and failure classification
• paused state on hard failures like bad repo/auth/config problems
• lifecycle commands to start, stop, restart, and inspect bridges

Core commands:

agentcodehandoff bridge-start --agent hermes --repo /path/to/repo
agentcodehandoff bridge-stop --agent hermes
agentcodehandoff bridge-restart --agent hermes --repo /path/to/repo
agentcodehandoff bridge-status

Smart Routing

agentcodehandoff route scores a request across the supported local agents:

• Hermes is preferred for docs, copy, README, install, review, and UX-oriented work
• Claude is preferred for architecture, planning, tradeoffs, and ambiguous deep-review work
• OpenClaw is preferred for memory, research, integrations, logs, and ops-oriented work

Examples:

agentcodehandoff route \
  --summary "Improve README onboarding" \
  --details "Tighten install wording and first-run instructions." \
  --files "README.md,install.sh"

agentcodehandoff dispatch \
  --from-agent claude \
  --summary "Fix parser bug" \
  --details "Investigate failing CLI state handling and route to the best agent." \
  --files "src/agentcodehandoff/cli.py"

Configuration

• Default state directory: ~/.agentcodehandoff
• Override with AGENTCODEHANDOFF_HOME
• Default wrapper directory: ~/.local/bin
• Default session state file: ~/.agentcodehandoff/sessions.json

Support Matrix

• Python: 3.10+
• Operating model: local-first, terminal-first
• Repo type: local git repositories
• Agent CLIs: Claude, Hermes, and OpenClaw are the primary supported agents today
• Platform expectation: Unix-like environments with git, python3, and standard process semantics

Runtime model

• Local machine: supported
• Shared repo on local filesystem: supported
• User-managed local agent CLIs: supported
• Hosted relay of third-party subscription credentials: not supported

Current support is strongest for:

• local development on macOS and Linux-style shells
• one machine coordinating two or three terminal agents
• repos where the local agent CLIs are already installed and authenticated

Current non-goals:

• hosted/cloud orchestration
• remote multi-machine coordination
• GUI-first workflows

Known Good Setups

These are the setups we currently feel best about for public alpha use:

• local-pair
  • Hermes + Claude
  • strongest option for simple local collaboration with low setup friction
• local-trio
  • Hermes + Claude + OpenClaw
  • best validated multi-agent setup today
  • live-verified with supervised bridges and real replies
• local-squad
  • Hermes + Claude + OpenClaw
  • fully integrated in the tool
  • best used when OpenClaw itself is already configured locally

Practical guidance:

• if you want the safest first experience, start with local-trio
• if Claude is unavailable or rate-limited, local-pair is still a strong path
• if you specifically want OpenClaw in the mix, use local-squad after confirming openclaw agent --json --agent main works locally

Public Alpha Roadmap

Near-term priorities:

• tighter onboarding based on real user feedback
• deeper OpenClaw live verification and setup guidance
• richer interactive ops actions in the terminal dashboard
• clearer request and bridge event history
• more regression coverage for long-running supervision behavior

Likely future work:

• richer TUI flows
• notifications
• optional relay modes that preserve the local-first model

Release Checklist

Before a broad public release, make sure all of these are true:

• python3 -m unittest discover -s tests -v passes
• python3 -m py_compile src/agentcodehandoff/cli.py tests/test_cli.py passes
• GitHub Actions CI is green
• install.sh works on a fresh machine/user profile
• doctor gives actionable output for missing CLIs and invalid repos
• up --template local-trio and down --template local-trio --force are verified in a disposable repo
• bridge-status, logs, ps, and dashboard --view ops all reflect the same bridge reality
• README examples still match the actual CLI flags and command names
• known limitations are still accurate
• screenshots or terminal captures are current

Contributing

See CONTRIBUTING.md.

Support

• bug reports: use the GitHub bug template and include ps, bridge-status, and logs output
• feature requests: use the GitHub feature template
• security issues: see SECURITY.md and report privately first

Changelog

See CHANGELOG.md.

License

See LICENSE.