agent-handshake

A universal protocol for autonomous AI agents to collaborate on the same codebase.

Two agents. One repo. Zero conflicts. No copy-paste middleman.

What This Solves

You have Claude fixing architecture. Antigravity running the pipeline. Cursor reviewing code. They all touch the same files. They cannot talk to each other. You are the messenger pigeon, copy-pasting between chat windows.

Agent Handshake eliminates the middleman. Agents communicate through a shared file (HANDSHAKE.md) using an append-only log protocol. A discovery script auto-finds where each agent stores its logs. Mirror logs give every agent visibility into what the others are doing.

Quick Start

1. Discover your agents

python scripts/discover_agents.py

Output:

INSTALLED:
  claude (Claude / Cowork)
    LOG: C:\Users\you\OneDrive\Documents\Claude\Scheduled\...
  antigravity (Antigravity / Google Gemini)
    LOG: C:\Users\you\AppData\Local\Temp\DiagOutputDir\Antigravity\Logs\...

2. Initialize your project

python scripts/discover_agents.py --init /path/to/your/project

This creates:

HANDSHAKE.md — pre-populated with discovered agents
logs/ — directory for mirror logs

3. Configure roles and rules

Edit HANDSHAKE.md:

Assign roles (operator, architect, reviewer) to each agent
Set your NORTH STAR (the canonical spec document)
Add project-specific rules

4. Give each agent its prompt

Copy the appropriate template from templates/:

prompt_operator.md — for the agent running your pipeline
prompt_architect.md — for the agent doing design work
prompt_reviewer.md — for the agent checking code quality

Fill in the bracketed fields and paste into your agent.

5. Start working

Both agents read and write to HANDSHAKE.md. You watch the LOG section. That is it.

6. Check agent health (v1.1)

python scripts/sync_check.py --project-root /path/to/your/project

Output:

AGENTS:
  [+] claude (Claude / Cowork) — architect
  [+] antigravity (Gemini / Antigravity) — operator

WARNINGS:
  [?] push: 1 PUSH REQUEST(s) with no PUSH COMPLETE

OK:
  [.] claude: Last seen: 2026-04-12 14:30
  [.] antigravity: Mirror log: 14 lines, 1.0 KB

STATUS: 0 alert(s), 1 warning(s) — review above

Any agent can run this — no special SDK. Pass --json for machine-readable output that agents can parse programmatically.

Use Cases

ComfyUI Multi-Model Pipelines (Primary)

The protocol was born here. ComfyUI custom node development involves:

LLM script generation, TTS voice acting, music generation, video rendering
16 GB VRAM ceiling with sequential model loading
Workflow JSON files that break when widget counts change
Multiple long-running production passes that need live monitoring

Setup: Claude/Cowork as Architect (designs node architecture, reviews Bug Bible, critiques narrative quality). Antigravity as Operator (monitors otr_runtime.log, repairs JSON workflows, manages VRAM boundaries, runs regression tests).

Real-world result: On the OldTimeRadio v2.0 project, this protocol enabled Claude to write architectural recommendations while Antigravity simultaneously ran a production pipeline. Antigravity implemented all four of Claude's priority fixes within one fix cycle, with zero coordination overhead from the human owner.

Game Development

Multiple agents working on different subsystems (rendering, AI, networking). The Operator monitors frame rates and crash logs. The Architect plans refactors across subsystems. The Reviewer checks for memory leaks and API misuse.

Web Application Development

Frontend agent (Cursor) building UI components. Backend agent (Claude) designing API endpoints. QA agent (Codex) running integration tests. All three coordinate through HANDSHAKE.md to avoid merge conflicts on shared types and interfaces.

Data Pipeline / ML Ops

Training agent monitors GPU utilization and loss curves. Architecture agent designs model improvements. Reviewer validates that changes do not regress on benchmark datasets.

DevOps / Infrastructure

Deploy agent manages Terraform and container orchestration. Architect agent plans infrastructure changes. Monitor agent watches production metrics and pages the team when thresholds are breached.

Supported Agents

Agent	Platform	Auto-Discovered
Claude / Cowork	Anthropic	Yes
Antigravity	Google / Gemini	Yes
Cursor	Anysphere	Yes
Windsurf	Codeium / Google	Yes
Codex CLI	OpenAI	Yes
GitHub Copilot	Microsoft / OpenAI	Yes
Aider	Open Source	Yes
Cline	VS Code Extension	Yes

Adding a new agent: edit AGENT_REGISTRY in scripts/discover_agents.py. PRs welcome.

Protocol Rules

Files are the only IPC. No APIs, no sockets, no databases. Just files on disk.
Append-only LOG. Nobody rewrites history. The LOG section is a ledger.
One-Writer Rule. Only one agent modifies a given file at a time. Log EDITING/EDIT_DONE markers.
Mirror logs. Each agent copies relevant log entries to logs/<name>_mirror.log — within 15 min of events, max 30 min idle.
Human authority. No agent merges, deploys, or ships without explicit human confirmation.
Roles are boundaries. An Operator does not architect. An Architect does not deploy.
Blocked Agent Protocol (v1.1) — Cannot complete a task? Log [BLOCKED], tail the other agent's mirror log, hand off. Never freeze silently.
3-Strike Rule (v1.1) — Same failure 3 times: stop everything, tail both logs, write [BLOCKED-3X]. No blind fourth retry.
Completion Verification (v1.3) — Before declaring MISSION COMPLETE, check that all expected output artifacts exist. Log ARTIFACT_CHECK. Missing artifacts = incomplete.
Heartbeat (v1.3) — Phases running > 30s must log progress every 60s. Silence > 120s is a hang signal.
Environment Health (v1.3) — Verify execution environment (API, GPU, disk, models) before and after every iteration. Log ENV_CHECK or ENV_DOWN.
Session Lifecycle (v1.3) — Log SESSION_START (with known state) and SESSION_END (with handoff notes). Returning agents re-check assumptions.
Task Ownership (v1.3) — Log TASK_CLAIM when starting work. 30-minute silence = abandoned. Any agent may TASK_RECLAIM.
Atomic Fixes (v1.3) — Multi-file fixes log FIX_START (full file list) and FIX_COMPLETE. Missing completion = partial fix.
Environment Changes (v1.3) — Config/model/dependency changes get an ENV_CHANGE log entry. Other agents must re-check assumptions.
Iteration Tagging (v1.3) — All entries during a run include [IT-NNN]. Enables cross-agent correlation.
Canonical Timestamps (v1.3) — All protocol entries use ISO-8601 with timezone: [2026-04-12T02:01:43-07:00].
Dispute Resolution (v1.3) — Disagreements logged with [DISPUTE] + evidence. Concrete evidence wins. Architect breaks ties.
Priority Interrupt (v1.3) — P0_INTERRUPT pauses all non-critical work. Only for blockers that stop everything.
Service Restart Policy (v1.3) — Projects define a RESTART_POLICY in HANDSHAKE.md: what service to monitor, what triggers a restart, what doesn't, and the exact restart procedure. The Operator executes restarts autonomously. The human never restarts the service manually. Includes dynamic service discovery — operators auto-detect process names, executable paths, and health endpoints instead of relying on hardcoded paths. Tiered autonomy (autonomous / preconditioned / human-gate) and a circuit breaker (3 restarts in 15 min = halt) prevent restart loops.
Git Push Protocol (v1.3) — Universal push escalation: GitHub API (most reliable, works from any sandbox) → native git with token → git with SSH → Windows MCP → human command block (last resort only). Lockstep verification mandatory after every push. Never commit tokens.
Protocol Feedback Loop (v1.3) — Production bugs feed back into the protocol. When an Operator fixes a bug, the Architect QA-reviews it and asks: "Did the protocol fail to prevent this?" If yes, a new rule or failure mode is added to agent-handshake. Bug → Fix → QA Review → Protocol Patch → Push. This is how the handshake self-improves.
Output Quality Gate (v1.3) -- Every iteration must pass automated quality checks (file integrity, content analysis, resource compliance, plan adherence) before being counted as successful. Artifact existence alone is not sufficient. The Architect defines which checks are required; the Operator runs them. Failed QA = failed iteration.
Promotion State Machine (v1.3) -- Projects with multiple workflow tiers (test/full) define an automated promotion ladder. Consecutive QA passes promote from test to full. Consecutive failures demote or halt. State persists to disk across session boundaries. No manual tier switching.
QA Report Archival (v1.3) -- Every QA gate result is appended to a structured JSONL log file. Enables trend analysis, regression detection, and post-mortem review. Rotate at 10 MB. Never truncate. See PROTOCOL.md for the full specification.

Ultra Experimental: Autonomous Release Loop

Opt-in mode where agents iterate forever, pushing versioned releases without human intervention. The cheap/fast agent grinds features. The expensive/smart agent gates quality — every cycle must earn its .1 version bump or get sent back.

Two push targets:

push_target: beta (default) — agents push to a beta branch, main stays untouched, you merge when ready
push_target: main (ambitious) — agents push directly to main, BUT a snapshot branch is created before every push so you can always roll back and never lose work

Safety rails: Snapshot branches before every main push. Full test suite green. AST parse on all changed files. No force push ever. Architect diff review required. 5 consecutive failed gates auto-pauses the loop. Max 1 push per hour.

See templates/prompt_auto_release.md for full setup.

File Structure

agent-handshake/
  README.md                # This file
  PROTOCOL.md              # Full protocol specification
  templates/
    HANDSHAKE_TEMPLATE.md  # Blank HANDSHAKE.md template
    prompt_operator.md     # System prompt for Operator role
    prompt_architect.md    # System prompt for Architect role
    prompt_reviewer.md     # System prompt for Reviewer role
    prompt_auto_release.md # Autonomous release loop (ultra experimental)
  scripts/
    discover_agents.py     # Auto-discover installed agents and log paths
    sync_check.py          # Health check — are your agents alive and in sync?
  examples/
    comfyui/               # ComfyUI multi-model pipeline example

Origin

Built by Jeffrey A. Brick during the OldTimeRadio v2.0 Visual Drama Engine project, April 2026. First implementation used Claude (Cowork) as Architect and Antigravity (Gemini) as Operator on an RTX 5080 running a 22-node ComfyUI pipeline.

The protocol emerged from a real problem: two AI agents kept overwriting each other's work, and Jeffrey was spending more time copy-pasting between chat windows than actually building. Agent Handshake reduced human coordination overhead to near zero.

License

MIT

Name		Name	Last commit message	Last commit date
examples/comfyui		examples/comfyui
scripts		scripts
templates		templates
.gitignore		.gitignore
PROTOCOL.md		PROTOCOL.md
README.md		README.md
REDDIT_POST.md		REDDIT_POST.md

Navigation Menu

Repository files navigation

agent-handshake

What This Solves

Quick Start

1. Discover your agents

2. Initialize your project

3. Configure roles and rules

4. Give each agent its prompt

5. Start working

6. Check agent health (v1.1)

Use Cases

ComfyUI Multi-Model Pipelines (Primary)

Game Development

Web Application Development

Data Pipeline / ML Ops

DevOps / Infrastructure

Supported Agents

Protocol Rules

Ultra Experimental: Autonomous Release Loop

File Structure

Origin

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

agent-handshake

What This Solves

Quick Start

1. Discover your agents

2. Initialize your project

3. Configure roles and rules

4. Give each agent its prompt

5. Start working

6. Check agent health (v1.1)

Use Cases

ComfyUI Multi-Model Pipelines (Primary)

Game Development

Web Application Development

Data Pipeline / ML Ops

DevOps / Infrastructure

Supported Agents

Protocol Rules

Ultra Experimental: Autonomous Release Loop

File Structure

Origin

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages