{"id":47928231,"url":"https://github.com/iriseye931-ai/agentcodehandoff","last_synced_at":"2026-04-04T07:01:53.280Z","repository":{"id":349073109,"uuid":"1200112376","full_name":"iriseye931-ai/agentcodehandoff","owner":"iriseye931-ai","description":"Local-first bring-your-own-agent control plane for coding agents with handoffs, supervision, routing, and recovery.","archived":false,"fork":false,"pushed_at":"2026-04-04T05:10:50.000Z","size":137,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T05:22:28.309Z","etag":null,"topics":["ai-agents","automation","bring-your-own-agent","claude","claude-code","codex","developer-tools","local-first","multi-agent","orchestration","terminal","terminal-agents"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iriseye931-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T03:43:32.000Z","updated_at":"2026-04-04T05:10:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iriseye931-ai/agentcodehandoff","commit_stats":null,"previous_names":["iriseye931-ai/agentcodehandoff"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/iriseye931-ai/agentcodehandoff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iriseye931-ai%2Fagentcodehandoff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iriseye931-ai%2Fagentcodehandoff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iriseye931-ai%2Fagentcodehandoff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iriseye931-ai%2Fagentcodehandoff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iriseye931-ai","download_url":"https://codeload.github.com/iriseye931-ai/agentcodehandoff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iriseye931-ai%2Fagentcodehandoff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31390695,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","bring-your-own-agent","claude","claude-code","codex","developer-tools","local-first","multi-agent","orchestration","terminal","terminal-agents"],"created_at":"2026-04-04T07:01:52.471Z","updated_at":"2026-04-04T07:01:53.251Z","avatar_url":"https://github.com/iriseye931-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/agentcodehandoff-lockup.svg\" alt=\"AgentCodeHandoff\" width=\"760\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eLocal control plane for bring-your-own coding agents.\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eA local-first shared handoff, supervision, and ops layer for Codex, Claude Code, Hermes, OpenClaw, and other terminal agents.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/iriseye931-ai/agentcodehandoff/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/iriseye931-ai/agentcodehandoff/ci.yml?branch=main\u0026label=CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/iriseye931-ai/agentcodehandoff/releases/tag/v0.1.0-alpha\"\u003e\u003cimg alt=\"Release\" src=\"https://img.shields.io/github/v/release/iriseye931-ai/agentcodehandoff?display_name=tag\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/iriseye931-ai/agentcodehandoff\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n`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.\n\nIt is intentionally a coordination layer, not a hosted model provider. You bring your own installed and configured agent tools. AgentCodeHandoff handles the collaboration.\n\n## Try This Now\n\n```bash\n./install.sh\nagentcodehandoff quickstart --repo /path/to/repo\nagentcodehandoff dashboard --view ops --interactive\n```\n\nThen send one real request:\n\n```bash\nagentcodehandoff request \\\n  --from-agent codex \\\n  --to-agent hermes \\\n  --summary \"Need help\" \\\n  --details \"Reply automatically with a short acknowledgement.\" \\\n  --files README.md\n```\n\nChoose your team:\n\n- `local-trio`: Codex + Hermes + Claude\n- `local-squad`: Codex + Hermes + Claude + OpenClaw\n- `local-pair`: Codex + Hermes\n\nIf you want the four-agent setup:\n\n```bash\nagentcodehandoff quickstart --template local-squad --repo /path/to/repo\n```\n\nCommon first-run fixes:\n\n- `agentcodehandoff doctor` if a bridge will not start. It now prints agent-specific next steps for missing or unauthenticated CLIs.\n- `agentcodehandoff doctor` also runs deeper runtime checks for Claude auth and Hermes provider reachability before you start bridges.\n- `agentcodehandoff agent-check --agent claude --repo /path/to/repo` if `claude auth status` looks healthy but the supervised Claude bridge still fails.\n- `agentcodehandoff agent-check --agent hermes --repo /path/to/repo` if Hermes is installed but timing out or not reaching its configured provider.\n- `agentcodehandoff bridge-status` if a bridge looks paused or stale. It now prints a remediation hint alongside the failure class and last error.\n- `agentcodehandoff logs --agents claude --lines 40` if Claude is installed but not replying\n- `agentcodehandoff logs --agents openclaw --lines 40` if OpenClaw is installed but not configured\n\n## Recovery\n\nIf `quickstart` or `up --template local-trio` does not get you to a healthy trio, run the agent-specific checks directly:\n\n```bash\nagentcodehandoff agent-check --agent claude --repo /path/to/repo\nagentcodehandoff agent-check --agent hermes --repo /path/to/repo\n```\n\nWhat they tell you:\n\n- `claude`:\n  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\n- `hermes`:\n  shows whether Hermes can reach its configured provider path and, on failure, reports the provider, model, and endpoint that timed out\n\nIf either one fails, fix that agent first and rerun:\n\n```bash\nagentcodehandoff quickstart --template local-trio --repo /path/to/repo\n```\n\nFor a concrete end-to-end example with real Claude and Hermes failure outputs, see [examples/recovery.md](examples/recovery.md).\nFor the four-agent setup, see [examples/local-squad-recovery.md](examples/local-squad-recovery.md).\n\n## Affected By The Claude Harness Policy?\n\nIf you still want Claude Code in the mix, but cannot rely on a third-party harness model anymore, this is the intended setup:\n\n- run your own installed `claude` CLI\n- run your own installed `codex` CLI\n- run your own configured `hermes` and optionally `openclaw` agent runtimes\n- let `AgentCodeHandoff` coordinate them in your environment\n\nStart here:\n\n```bash\nagentcodehandoff quickstart --template local-trio --repo /path/to/repo\n```\n\nIf Claude still fails even though `claude auth status` looks fine:\n\n```bash\nagentcodehandoff agent-check --agent claude --repo /path/to/repo\n```\n\nThat reproduces the real bridge invocation path and tells you exactly what to fix next.\n\nIf you are using the four-agent squad, also run:\n\n```bash\nagentcodehandoff agent-check --agent openclaw --repo /path/to/repo\n```\n\nand use [examples/local-squad-recovery.md](examples/local-squad-recovery.md) as the recovery checklist.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/agentcodehandoff-demo.svg\" alt=\"AgentCodeHandoff terminal demo\" width=\"920\" /\u003e\n\u003c/p\u003e\n\nIt is built for teams running:\n\n- Codex + Claude + Hermes\n- Codex + Claude + Hermes + OpenClaw\n- two or more agent terminals on one machine\n- one shared codebase\n- a zero-infrastructure workflow\n\nIt now supports:\n\n- 3-agent supervised team startup with `local-trio`\n- 4-agent supervised team startup with `local-squad`\n- availability-aware routing and graceful fallback when one agent is rate-limited or offline\n- interactive terminal ops for recovery, sweeping, and request resolution\n- live-verified Claude bridge replies via structured JSON output\n\n## Why Teams Need It\n\nMost multi-agent coding workflows break on coordination, not model quality:\n\n- no durable handoff stream\n- no clear ownership of files or scopes\n- no quick way to see who is doing what\n- no shared notion of blocked, done, or review-ready work\n- too much manual relaying between terminals\n\n`agentcodehandoff` fixes that with a small, explicit local state model:\n\n- `~/.agentcodehandoff/inbox.jsonl`\n- `~/.agentcodehandoff/claims.json`\n\n## What This Is\n\n- A local-first coordination layer for Codex, Claude Code, Hermes, OpenClaw, and similar terminal agents\n- A shared handoff, routing, supervision, and recovery system that runs on your machine\n- A way to make already-installed agents collaborate inside one repo without constant human relaying\n\n## What This Is Not\n\n- Not a hosted agent platform\n- Not a model provider\n- Not a third-party Claude subscription harness\n- Not a resale layer for API or subscription access\n\n## Authentication Model\n\nAgentCodeHandoff follows a bring-your-own-agent model:\n\n- for subscription-backed tools like `codex` and `claude`, you use your own installed and authenticated CLIs in your environment\n- for harness-style tools like `hermes` and `openclaw`, you use your own configured runtimes, providers, and local setup\n- AgentCodeHandoff launches and coordinates those tools; it does not provide the underlying subscriptions, providers, or models\n\nThis 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.\n\n## What It Includes\n\n- Shared inbox for agent-to-agent handoffs\n- Lightweight claim board for file and scope ownership\n- Availability-aware routing across Codex, Hermes, and Claude\n- Workflow updates for `request`, `done`, `blocked`, and `review`\n- Request lifecycle tracking with `acknowledged`, `done`, `blocked`, `review`, `closed`, `approved`, and `escalated`\n- Claim resolution with final states like `completed`, `blocked`, and `abandoned`\n- Git worktree-backed agent sessions for isolated edit space\n- File-awareness checks that compare live session edits to claimed files\n- Drift suggestions and safe remediation for expand, handoff, and split-work flows\n- Supervised bridge lifecycle commands with pid, heartbeat, and pending request visibility\n- Saved bridge profiles, reusable presets, and one-command team lifecycle controls\n- Automatic timeout recovery with reminders, reroutes, and escalation when safe recovery is exhausted\n- Terminal-first workflow for two or more agents in one repo\n- Paneled terminal dashboard for bridge health, workflow, requests, claims, conflicts, and recent messages\n- Interactive ops dashboard with direct recovery and request-resolution shortcuts\n- Local-first state with no daemon required\n- Agent-specific wrapper commands for faster day-to-day use\n\n## Current State\n\nThis repo is no longer just a shared inbox prototype. The current build supports:\n\n- local pair and local trio presets\n- local squad preset with OpenClaw support\n- supervised `up` / `down` / `restart-team` lifecycle commands\n- persistent bridge recovery profiles\n- interactive operator controls from the terminal dashboard\n- explicit availability overrides for rate-limited or offline agents\n- live trio verification with Codex, Hermes, and Claude\n\n## First 5 Minutes\n\nIf you want the fastest path from clone to real collaboration, use the golden path:\n\n```bash\nagentcodehandoff quickstart --repo /path/to/repo\n```\n\nThat will:\n\n- initialize local state\n- install wrappers\n- run setup checks\n- start the default supervised local trio\n- print the next commands to use\n\nThen open the operator view:\n\n```bash\nagentcodehandoff dashboard --view ops --interactive\n```\n\nAnd send one real request:\n\n```bash\nagentcodehandoff request \\\n  --from-agent codex \\\n  --to-agent hermes \\\n  --summary \"Need help\" \\\n  --details \"Reply automatically with a short acknowledgement.\" \\\n  --files README.md\n```\n\nGuided examples:\n\n- [First 5 Minutes](examples/first-5-minutes.md)\n- [Supervised Bridge Workflow](examples/supervised-bridge-workflow.md)\n- [Local Squad Workflow](examples/local-squad-workflow.md)\n\n## Public Alpha Verification\n\nThe current build has been verified against the real local toolchain, not just isolated tests.\n\nLive verification completed with:\n\n- `agentcodehandoff up --template local-trio`\n- real supervised bridges for Codex, Hermes, and Claude\n- real requests sent through AgentCodeHandoff into the shared inbox\n- real automatic replies written back by Hermes and Claude\n\nObserved live replies:\n\n- `hermes -\u003e codex`\n  - `Acknowledged public release verification`\n- `claude -\u003e codex`\n  - `ACK: Public release live verification task received`\n\nThat 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.\n\nOpenClaw 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.\n\n## Positioning\n\nThe product story is intentionally simple:\n\n- you already have agent tools\n- you already pay for them however you choose\n- AgentCodeHandoff makes them coordinate\n\nThat keeps the tool lightweight, local, and practical for real engineering workflows.\n\n## FAQ\n\n### Is this a hosted harness for Claude or other agent subscriptions?\n\nNo. AgentCodeHandoff is a coordination layer. You run your own installed agent tools and keep auth or provider setup in those tools. AgentCodeHandoff coordinates them.\n\n### Is this useful if I am affected by stricter Claude policy around third-party harnesses?\n\nYes. 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 Codex, Hermes, OpenClaw, or other agent tools in your environment.\"\n\n### Does OpenClaw work here?\n\nYes, 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.\n\n### Do I need to pay API costs through AgentCodeHandoff?\n\nNo. 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.\n\n### What is the fastest way to see it working?\n\nRun:\n\n```bash\n./install.sh\nagentcodehandoff quickstart --repo /path/to/repo\nagentcodehandoff dashboard --view ops --interactive\n```\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/agentcodehandoff-architecture.svg\" alt=\"AgentCodeHandoff architecture\" width=\"920\" /\u003e\n\u003c/p\u003e\n\n## Quick Start\n\n```bash\ncd agent-inbox\n./install.sh\n```\n\nThat installs the CLI, creates the local state directory, seeds bootstrap messages, and installs helper wrappers under `~/.local/bin`.\n\nTry a disposable end-to-end demo:\n\n```bash\n./examples/demo-session.sh\n```\n\nFor the full supervised collaboration path, start with:\n\n1. `agentcodehandoff doctor`\n2. `agentcodehandoff up --template local-trio --repo /path/to/repo`\n3. `agentcodehandoff dashboard --view ops --interactive`\n4. `agentcodehandoff bridge-status`\n5. `agentcodehandoff requests`\n6. `agentcodehandoff availability`\n\nIf you are the second collaborator terminal, keep this shorter loop:\n\n1. `agentcodehandoff-hermes-watch`\n2. `agentcodehandoff dashboard --view ops`\n3. `agentcodehandoff bridge-status`\n4. `agentcodehandoff bridge-profile-show --agent hermes`\n\n## First Run\n\n```bash\nagentcodehandoff doctor\nagentcodehandoff status\n```\n\nFor a read-only observer setup, start two terminals:\n\n```bash\nagentcodehandoff-codex-watch\nagentcodehandoff-hermes-watch\nagentcodehandoff-claude-watch\n```\n\nFor manually managed auto-reply bridges, start them in real terminals:\n\n```bash\nagentcodehandoff-codex-auto --repo /Users/iris/Projects/agent-inbox\nagentcodehandoff-hermes-auto --repo /Users/iris/Projects/agent-inbox\nagentcodehandoff-claude-auto --repo /Users/iris/Projects/agent-inbox\nagentcodehandoff-openclaw-auto --repo /Users/iris/Projects/agent-inbox\n```\n\nEnable automatic file claims from bridge replies:\n\n```bash\nagentcodehandoff-hermes-auto --repo /Users/iris/Projects/agent-inbox --claim-on-files\n```\n\nCheck whether the bridges appear alive:\n\n```bash\nagentcodehandoff auto-status\n```\n\nOverride an agent's availability when you already know it is offline or rate-limited:\n\n```bash\nagentcodehandoff availability-set --agent claude --state rate-limited --note \"subscription window exhausted\"\nagentcodehandoff availability\n```\n\nFor day-to-day supervised operation, prefer managed background bridges instead of keeping separate reply terminals open:\n\n```bash\nagentcodehandoff bridge-start --agent codex --repo /path/to/repo --auto-sweep\nagentcodehandoff bridge-start --agent hermes --repo /path/to/repo --auto-sweep\nagentcodehandoff bridge-start --agent claude --repo /path/to/repo --auto-sweep\nagentcodehandoff bridge-start --agent openclaw --repo /path/to/repo --auto-sweep\n```\n\nOr apply the built-in trio preset in one step:\n\n```bash\nagentcodehandoff bridge-preset-apply --name local-trio --repo /path/to/repo --start\n```\n\nOr bring up the built-in four-agent preset:\n\n```bash\nagentcodehandoff bridge-preset-apply --name local-squad --repo /path/to/repo --start\n```\n\nOr use the higher-level team lifecycle commands:\n\n```bash\nagentcodehandoff up --template local-trio --repo /path/to/repo\nagentcodehandoff up --template local-squad --repo /path/to/repo\nagentcodehandoff down --template local-trio --repo /path/to/repo\nagentcodehandoff restart-team --template local-trio --repo /path/to/repo\n```\n\nThe `local-trio` flow has been live-verified with Codex, Hermes, and Claude replying through supervised bridges.\n\n## Visuals\n\nPrimary assets in this repo:\n\n- brand mark: `assets/agentcodehandoff-mark.svg`\n- README lockup: `assets/agentcodehandoff-lockup.svg`\n- social preview: `assets/agentcodehandoff-social-preview.svg`\n\nFor GitHub repo presentation, use `assets/agentcodehandoff-social-preview.svg` as the social preview image.\n\nFor live terminal operations, enable dashboard actions:\n\n```bash\nagentcodehandoff dashboard --view ops --interactive\n```\n\nKeys:\n- `a` apply the top safe ops action\n- `r` recover bridges\n- `s` sweep stale requests\n- `p` approve the top actionable request resolution\n- `c` close the top actionable request resolution\n- `e` escalate the top actionable request resolution\n- `q` quit\n\nInspect supervised bridge health:\n\n```bash\nagentcodehandoff events --limit 20\nagentcodehandoff request-trace --request-id \u003crequest-id\u003e\nagentcodehandoff ps\nagentcodehandoff bridge-status\nagentcodehandoff logs --agents claude --lines 40\nagentcodehandoff bridge-profiles\nagentcodehandoff bridge-presets\n```\n\nOpen the live terminal dashboard. Use the default view for coordination and the ops view for bridge supervision, stale requests, and recovery visibility:\n\n```bash\nagentcodehandoff-dashboard\nagentcodehandoff dashboard --view ops\nagentcodehandoff ops-next\n```\n\nSend a handoff:\n\n```bash\nagentcodehandoff-codex-send \\\n  --summary \"Need a realism pass\" \\\n  --details \"Own MeshGraph.tsx only\" \\\n  --files \"frontend/src/components/MeshGraph.tsx\"\n```\n\nSend an auto-reply request:\n\n```bash\nagentcodehandoff-codex-request \\\n  --summary \"Need a quick review\" \\\n  --details \"Reply automatically with short feedback.\" \\\n  --files \"README.md\"\n```\n\nRoute a request automatically:\n\n```bash\nagentcodehandoff dispatch \\\n  --from-agent codex \\\n  --summary \"Fix failing CLI test\" \\\n  --details \"Investigate the parser behavior and send it to the best agent automatically.\" \\\n  --files \"src/agentcodehandoff/cli.py,README.md\"\n```\n\nClaim a scope:\n\n```bash\nagentcodehandoff-hermes-claim \\\n  --scope meshgraph-pass \\\n  --summary \"Owning cinematic sphere polish\" \\\n  --files \"frontend/src/components/MeshGraph.tsx\"\n```\n\nSend a completion update:\n\n```bash\nagentcodehandoff-codex-done \\\n  --summary \"CLI workflow states shipped\" \\\n  --details \"done, blocked, review, and claim resolution are live.\" \\\n  --files \"src/agentcodehandoff/cli.py,README.md\"\n```\n\nSignal a blocker:\n\n```bash\nagentcodehandoff-hermes-blocked \\\n  --summary \"Need routing policy input\" \\\n  --details \"Current heuristics are too generic for design-vs-code review tasks.\" \\\n  --files \"src/agentcodehandoff/cli.py\"\n```\n\nRequest review:\n\n```bash\nagentcodehandoff-codex-review \\\n  --summary \"Review the dispatch heuristics\" \\\n  --details \"Check whether docs-heavy mixed tasks should route to Hermes.\" \\\n  --files \"src/agentcodehandoff/cli.py,README.md\"\n```\n\nResolve a claim:\n\n```bash\nagentcodehandoff resolve \\\n  --agent codex \\\n  --scope cli-workflow-pass \\\n  --status completed \\\n  --note \"Merged and verified locally.\"\n```\n\nStart an isolated worktree session:\n\n```bash\nagentcodehandoff session-start \\\n  --agent codex \\\n  --scope parser-pass \\\n  --repo /path/to/repo \\\n  --note \"Isolated parser refactor worktree\"\n```\n\nList sessions:\n\n```bash\nagentcodehandoff sessions\n```\n\nClose a session and remove its worktree:\n\n```bash\nagentcodehandoff session-end \\\n  --agent codex \\\n  --scope parser-pass \\\n  --note \"Merged and cleaned up\"\n```\n\nInspect live drift against claimed files:\n\n```bash\nagentcodehandoff drift\n```\n\nGet actionable scope suggestions:\n\n```bash\nagentcodehandoff suggest\n```\n\nInspect request lifecycle state:\n\n```bash\nagentcodehandoff requests\n```\n\nResolve a tracked request explicitly:\n\n```bash\nagentcodehandoff request-resolve --request-id msg-123 --action approve\nagentcodehandoff request-resolve --request-id msg-123 --action close\n```\n\nSweep stale requests and apply timeout actions:\n\n```bash\nagentcodehandoff request-sweep\n```\n\nLet supervised bridges recover their own stale requests automatically:\n\n```bash\nagentcodehandoff bridge-start --agent codex --repo /path/to/repo --auto-sweep --sweep-interval 30 --max-restarts 5\n```\n\nRecover paused or down bridges with one command:\n\n```bash\nagentcodehandoff bridge-recover\n```\n\nBridge recovery uses the last saved per-agent profile even after a full stop removes the live lock.\n\n## Recommended Onboarding For Codex + Claude/Hermes\n\nThis is the clearest path for two-agent collaboration in one shared repo.\n\n1. Install and verify local state.\n\n```bash\n./install.sh\nagentcodehandoff doctor\n```\n\n2. Start supervised bridges for each agent that should auto-reply.\n\n```bash\nagentcodehandoff bridge-start --agent codex --repo /path/to/repo --auto-sweep\nagentcodehandoff bridge-start --agent hermes --repo /path/to/repo --auto-sweep\n```\n\n3. Keep one terminal on the ops dashboard.\n\n```bash\nagentcodehandoff dashboard --view ops\n```\n\n4. In active agent terminals, use claims plus `request`, `done`, `blocked`, and `review` updates.\n\n5. If a bridge stops responding, inspect it first:\n\n```bash\nagentcodehandoff bridge-status\nagentcodehandoff requests\nagentcodehandoff request-sweep\n```\n\n6. If the bridge is down or paused, recover it using the saved profile:\n\n```bash\nagentcodehandoff bridge-recover\n```\n\n7. If recovery is exhausted, fall back to manual auto terminals:\n\n```bash\nagentcodehandoff-codex-auto --repo /path/to/repo\nagentcodehandoff-hermes-auto --repo /path/to/repo\n```\n\nThis gives a clean split:\n\n- supervised bridges for normal unattended routing\n- ops dashboard for health and stale-request visibility\n- manual auto terminals as a safe fallback during bring-up or debugging\n\n## Supervised Bridge Workflow\n\nUse this when you want the tool to keep automation alive without manual babysitting.\n\nStart bridges:\n\n```bash\nagentcodehandoff bridge-start --agent codex --repo /path/to/repo --auto-sweep\nagentcodehandoff bridge-start --agent hermes --repo /path/to/repo --auto-sweep\n```\n\nInspect health:\n\n```bash\nagentcodehandoff bridge-status\nagentcodehandoff dashboard --view ops\n```\n\nCommon checks:\n\n- `bridge-status` for pid, heartbeat, pending requests, restart counts, and saved profile timestamps\n- `dashboard --view ops` for at-a-glance bridge state, stale requests, and remediation context\n- `requests` and `request-sweep` when work is stuck but the bridge still appears alive\n\nStop or restart a specific bridge:\n\n```bash\nagentcodehandoff bridge-stop --agent codex\nagentcodehandoff bridge-restart --agent codex --repo /path/to/repo\n```\n\n## Profile Recovery Workflow\n\nSupervised bridges persist a per-agent profile so recovery does not depend on a live lock file surviving.\n\nTypical recovery loop:\n\n1. A bridge is down, paused, or missing after a shell restart.\n2. `agentcodehandoff bridge-status` shows no healthy live process, but still shows the saved repo profile.\n3. `agentcodehandoff bridge-recover` restarts the bridge using the last saved settings.\n4. `agentcodehandoff dashboard --view ops` confirms heartbeat and pending request state.\n\nExample:\n\n```bash\nagentcodehandoff bridge-status\nagentcodehandoff bridge-recover\nagentcodehandoff bridge-status\n```\n\nUse `bridge-recover --fail-if-idle` in scripts when you want a non-zero exit if nothing actually needed recovery.\n\nInspect or delete a saved bridge profile:\n\n```bash\nagentcodehandoff bridge-profile-show --agent codex\nagentcodehandoff bridge-profile-delete --agent hermes\n```\n\nSave reusable bridge presets and apply them later:\n\n```bash\nagentcodehandoff bridge-preset-save --name local-pair --agents codex hermes\nagentcodehandoff bridge-preset-apply --name local-pair --start\n```\n\nAsk the tool for the single most important next ops action:\n\n```bash\nagentcodehandoff ops-next\nagentcodehandoff ops-next --apply\nagentcodehandoff ops-next --apply --create-session\n```\n\nApply a safe remediation automatically:\n\n```bash\nagentcodehandoff remediate --agent codex --scope parser-pass\n```\n\nCreate a new split scope and session when drift becomes separate work:\n\n```bash\nagentcodehandoff remediate --agent codex --scope parser-pass --create-session\n```\n\n## Core Commands\n\n```bash\nagentcodehandoff init --install-wrappers --seed\nagentcodehandoff doctor\nagentcodehandoff read --agent codex\nagentcodehandoff watch --agent hermes\nagentcodehandoff latest --agent hermes\nagentcodehandoff events\nagentcodehandoff request-trace --request-id \u003crequest-id\u003e\nagentcodehandoff status\nagentcodehandoff auto-status\nagentcodehandoff dashboard\nagentcodehandoff-dashboard\nagentcodehandoff-status\nagentcodehandoff claims\nagentcodehandoff sessions\nagentcodehandoff drift\nagentcodehandoff suggest\nagentcodehandoff requests\nagentcodehandoff request-sweep\nagentcodehandoff remediate --agent codex --scope parser-pass\nagentcodehandoff bridge-status\nagentcodehandoff resolve --agent codex --scope cli-pass --status completed\n```\n\n## Demo\n\n`examples/demo-session.sh` runs a safe local session in `/tmp`:\n\n- initializes state\n- creates wrappers\n- records a claim\n- sends a request-style handoff\n- prints status\n- prints the next supervised bridge and ops commands to try in a real repo\n\n## Testing\n\nRun the current critical-path test suite with:\n\n```bash\npython3 -m unittest discover -s tests -v\n```\n\nThe current suite covers:\n\n- `init` and `doctor` against isolated fake Codex, Hermes, Claude, and OpenClaw CLIs\n- availability overrides and routing fallback\n- bridge preset persistence for `local-trio`\n- bridge preset persistence for `local-squad`\n- bridge startup validation for missing agent CLIs and non-git repos\n- stale lock cleanup and paused-bridge recovery from saved profiles\n- restart-cap pause behavior for supervised bridges\n- merged bridge/message timeline via `events`\n- per-request lifecycle trace via `request-trace`\n- per-agent bridge log access\n- compact per-agent team summaries with `ps`\n- supervised `local-trio` startup plus an actual Claude bridge reply in an isolated temp repo\n- supervised `local-squad` startup with OpenClaw included in the team health path\n- tracked request resolution\n- golden-path `quickstart` onboarding\n\nThis 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.\n\n## Known Limitations\n\n- Agent bridge behavior still depends on the local Codex, Claude, and Hermes CLIs being installed and authenticated in the environment that launches the bridge.\n- 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.\n- Real provider/runtime differences can still surface outside the isolated fake-agent test suite.\n- The dashboard is terminal-first and intentionally lightweight; it is not a full graphical control plane.\n- The current test suite is strong on critical paths, but not yet exhaustive across every command combination.\n- Claude Code behavior depends on the local `claude` CLI being installed and authenticated in the same runtime environment where the bridge process is launched.\n\n## Wrapper Commands\n\nInstalled by `agentcodehandoff init --install-wrappers`:\n\n- `agentcodehandoff-dashboard`\n- `agentcodehandoff-auto-status`\n- `agentcodehandoff-events`\n- `agentcodehandoff-request-trace`\n- `agentcodehandoff-status`\n- `agentcodehandoff-sessions`\n- `agentcodehandoff-drift`\n- `agentcodehandoff-suggest`\n- `agentcodehandoff-requests`\n- `agentcodehandoff-request-sweep`\n- `agentcodehandoff-remediate`\n- `agentcodehandoff-availability`\n- `agentcodehandoff-availability-set`\n- `agentcodehandoff-quickstart`\n- `agentcodehandoff-up`\n- `agentcodehandoff-down`\n- `agentcodehandoff-restart-team`\n- `agentcodehandoff-bridge-status`\n- `agentcodehandoff-codex-watch`\n- `agentcodehandoff-hermes-watch`\n- `agentcodehandoff-claude-watch`\n- `agentcodehandoff-openclaw-watch`\n- `agentcodehandoff-codex-read`\n- `agentcodehandoff-hermes-read`\n- `agentcodehandoff-claude-read`\n- `agentcodehandoff-openclaw-read`\n- `agentcodehandoff-codex-auto`\n- `agentcodehandoff-hermes-auto`\n- `agentcodehandoff-claude-auto`\n- `agentcodehandoff-openclaw-auto`\n- `agentcodehandoff-codex-send`\n- `agentcodehandoff-hermes-send`\n- `agentcodehandoff-claude-send`\n- `agentcodehandoff-openclaw-send`\n- `agentcodehandoff-codex-request`\n- `agentcodehandoff-hermes-request`\n- `agentcodehandoff-claude-request`\n- `agentcodehandoff-openclaw-request`\n- `agentcodehandoff-codex-claim`\n- `agentcodehandoff-hermes-claim`\n- `agentcodehandoff-claude-claim`\n- `agentcodehandoff-openclaw-claim`\n- `agentcodehandoff-codex-done`\n- `agentcodehandoff-hermes-done`\n- `agentcodehandoff-claude-done`\n- `agentcodehandoff-openclaw-done`\n- `agentcodehandoff-codex-blocked`\n- `agentcodehandoff-hermes-blocked`\n- `agentcodehandoff-claude-blocked`\n- `agentcodehandoff-openclaw-blocked`\n- `agentcodehandoff-codex-review`\n- `agentcodehandoff-hermes-review`\n- `agentcodehandoff-claude-review`\n- `agentcodehandoff-openclaw-review`\n- `agentcodehandoff-codex-release`\n- `agentcodehandoff-hermes-release`\n- `agentcodehandoff-claude-release`\n- `agentcodehandoff-openclaw-release`\n\n## Typical Workflow\n\n1. Agent A claims a bounded scope.\n2. Agent B claims a non-overlapping scope.\n3. Both agents keep `watch` or `dashboard` running.\n4. Use `request` for work that expects a response.\n5. Use `done`, `blocked`, or `review` so progress reads like a workflow, not raw chat.\n6. Resolve claims with `completed`, `blocked`, or `abandoned` when work closes out.\n7. Use `agentcodehandoff status` to inspect latest handoffs, workflow events, open claims, and recently resolved claims.\n\n## Terminal Dashboard\n\n`agentcodehandoff-dashboard` is the fastest way to understand live system state in one terminal.\n\nIt shows:\n\n- bridge health for Codex, Hermes, and Claude\n- latest handoffs\n- workflow events like `request`, `blocked`, `review`, and `done`\n- open claims\n- claim conflicts\n- recently resolved claims\n- recent message traffic\n- active worktree sessions\n- file-awareness drift summaries\n- actionable suggestions for expand, split, or handoff decisions\n- safe remediation helpers for claim expansion and handoff generation\n- split-work remediation that can create a new claim and optional session\n- request lifecycle tracking with pending, acknowledged, stale, and outcome states\n- stale-request sweep for reminders and reroutes\n\n## Worktree Sessions\n\n`agentcodehandoff` can manage isolated git worktrees per agent and scope.\n\nUse this when you want:\n\n- one agent per branch/worktree\n- clean physical separation of edits\n- session state that matches claim state\n- dashboard visibility into who owns which workspace\n\nBy default, sessions create worktrees under:\n\n- `\u003crepo\u003e/.worktrees/\u003cagent\u003e-\u003cscope-slug\u003e`\n\nDefault branch naming:\n\n- `ach/\u003cagent\u003e/\u003cscope-slug\u003e`\n\nCore commands:\n\n```bash\nagentcodehandoff session-start --agent codex --scope parser-pass --repo /path/to/repo\nagentcodehandoff sessions\nagentcodehandoff drift\nagentcodehandoff suggest\nagentcodehandoff session-end --agent codex --scope parser-pass\n```\n\n## Auto Reply\n\n`agentcodehandoff auto --agent \u003cname\u003e` watches the inbox and uses a local agent CLI to generate a JSON reply automatically.\n\n- `hermes` uses `hermes chat -Q -q`\n- `codex` uses `codex --sandbox read-only exec`\n- `claude` uses `claude -p`\n- `openclaw` uses `openclaw agent --json --agent main`\n\nExample:\n\n```bash\nagentcodehandoff-hermes-auto --repo /Users/iris/Projects/agent-inbox\nagentcodehandoff-codex-auto --repo /Users/iris/Projects/agent-inbox\nagentcodehandoff-claude-auto --repo /Users/iris/Projects/agent-inbox\nagentcodehandoff auto-status\n```\n\nAuto-claim example:\n\n```bash\nagentcodehandoff-hermes-auto \\\n  --repo /Users/iris/Projects/agent-inbox \\\n  --claim-on-files\n```\n\nNotes:\n\n- `claude` requires a valid Claude Code CLI login in the shell environment where the bridge runs.\n- `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.\n- smart routing automatically deprioritizes agents with auth, rate-limit, or paused bridge failures when supervision state is available.\n\n- this works only in a real terminal environment where Hermes and Codex can reach their providers\n- it is not expected to work inside a restricted offline sandbox\n- the auto bridge only replies to messages addressed to that agent\n- auto bridges only respond to `request`, `task`, and `auto-request` roles\n- plain `handoff` messages are informational and do not auto-trigger replies\n\n## Bridge Supervision\n\nSupervised bridges let the tool keep automation running without constant manual babysitting.\n\nWhat supervision adds:\n\n- one managed background bridge per agent\n- pid and heartbeat tracking\n- pending request visibility\n- log file paths for bridge output\n- restart counts and failure classification\n- paused state on hard failures like bad repo/auth/config problems\n- lifecycle commands to start, stop, restart, and inspect bridges\n\nCore commands:\n\n```bash\nagentcodehandoff bridge-start --agent codex --repo /path/to/repo\nagentcodehandoff bridge-stop --agent codex\nagentcodehandoff bridge-restart --agent codex --repo /path/to/repo\nagentcodehandoff bridge-status\n```\n\n## Smart Routing\n\n`agentcodehandoff route` scores a request across the supported local agents:\n\n- Hermes is preferred for docs, copy, README, install, review, and UX-oriented work\n- Codex is preferred for bugs, tests, refactors, CLI/code changes, and build/debug work\n- Claude is preferred for architecture, planning, tradeoffs, and ambiguous deep-review work\n- OpenClaw is preferred for memory, research, integrations, logs, and ops-oriented work\n\nExamples:\n\n```bash\nagentcodehandoff route \\\n  --summary \"Improve README onboarding\" \\\n  --details \"Tighten install wording and first-run instructions.\" \\\n  --files \"README.md,install.sh\"\n```\n\n```bash\nagentcodehandoff dispatch \\\n  --from-agent codex \\\n  --summary \"Fix parser bug\" \\\n  --details \"Investigate failing CLI state handling and route to the best agent.\" \\\n  --files \"src/agentcodehandoff/cli.py\"\n```\n\n## Configuration\n\n- Default state directory: `~/.agentcodehandoff`\n- Override with `AGENTCODEHANDOFF_HOME`\n- Default wrapper directory: `~/.local/bin`\n- Default session state file: `~/.agentcodehandoff/sessions.json`\n\n## Support Matrix\n\n- Python: `3.10+`\n- Operating model: local-first, terminal-first\n- Repo type: local git repositories\n- Agent CLIs: Codex, Claude, Hermes, and OpenClaw are the primary supported agents today\n- Platform expectation: Unix-like environments with `git`, `python3`, and standard process semantics\n\n### Runtime model\n\n- Local machine: supported\n- Shared repo on local filesystem: supported\n- User-managed local agent CLIs: supported\n- Hosted relay of third-party subscription credentials: not supported\n\nCurrent support is strongest for:\n\n- local development on macOS and Linux-style shells\n- one machine coordinating two or three terminal agents\n- repos where the local agent CLIs are already installed and authenticated\n\nCurrent non-goals:\n\n- hosted/cloud orchestration\n- remote multi-machine coordination\n- GUI-first workflows\n\n## Known Good Setups\n\nThese are the setups we currently feel best about for public alpha use:\n\n- `local-pair`\n  - Codex + Hermes\n  - strongest option for simple local collaboration with low setup friction\n- `local-trio`\n  - Codex + Hermes + Claude\n  - best validated multi-agent setup today\n  - live-verified with supervised bridges and real replies\n- `local-squad`\n  - Codex + Hermes + Claude + OpenClaw\n  - fully integrated in the tool\n  - best used when OpenClaw itself is already configured locally\n\nPractical guidance:\n\n- if you want the safest first experience, start with `local-trio`\n- if Claude is unavailable or rate-limited, `local-pair` is still a strong path\n- if you specifically want OpenClaw in the mix, use `local-squad` after confirming `openclaw agent --json --agent main` works locally\n\n## Public Alpha Roadmap\n\nNear-term priorities:\n\n- tighter onboarding based on real user feedback\n- deeper OpenClaw live verification and setup guidance\n- richer interactive ops actions in the terminal dashboard\n- clearer request and bridge event history\n- more regression coverage for long-running supervision behavior\n\nLikely future work:\n\n- richer TUI flows\n- notifications\n- optional relay modes that preserve the local-first model\n\n## Release Checklist\n\nBefore a broad public release, make sure all of these are true:\n\n- `python3 -m unittest discover -s tests -v` passes\n- `python3 -m py_compile src/agentcodehandoff/cli.py tests/test_cli.py` passes\n- GitHub Actions CI is green\n- `install.sh` works on a fresh machine/user profile\n- `doctor` gives actionable output for missing CLIs and invalid repos\n- `up --template local-trio` and `down --template local-trio --force` are verified in a disposable repo\n- `bridge-status`, `logs`, `ps`, and `dashboard --view ops` all reflect the same bridge reality\n- README examples still match the actual CLI flags and command names\n- known limitations are still accurate\n- screenshots or terminal captures are current\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Support\n\n- bug reports: use the GitHub bug template and include `ps`, `bridge-status`, and `logs` output\n- feature requests: use the GitHub feature template\n- security issues: see [SECURITY.md](SECURITY.md) and report privately first\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n## License\n\nSee [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firiseye931-ai%2Fagentcodehandoff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Firiseye931-ai%2Fagentcodehandoff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firiseye931-ai%2Fagentcodehandoff/lists"}