Skip to content
BranchesTags

Repository files navigation

      ███████╗██╗   ██╗███████╗     ██████╗ ███████╗     ██████╗  ██████╗ ██████╗
      ██╔════╝╚██╗ ██╔╝██╔════╝    ██╔═══██╗██╔════╝    ██╔════╝ ██╔═══██╗██╔══██╗
      █████╗   ╚████╔╝ █████╗      ██║   ██║█████╗      ██║  ███╗██║   ██║██║  ██║
      ██╔══╝    ╚██╔╝  ██╔══╝      ██║   ██║██╔══╝      ██║   ██║██║   ██║██║  ██║
      ███████╗   ██║   ███████╗    ╚██████╔╝██║         ╚██████╔╝╚██████╔╝██████╔╝
      ╚══════╝   ╚═╝   ╚══════╝     ╚═════╝ ╚═╝          ╚═════╝  ╚═════╝ ╚═════╝

    The localhost agent mesh protocol. Zero config. Any vendor. One broker.

Eye of God

A protocol for AI agents to discover and talk to each other on localhost.

Protocol Spec   Zero Config   Bun   MIT License

Protocol Spec   •   Problem   •   Quick Start   •   Dashboard   •   Integrations

The Protocol

Everyone assumes agent-to-agent communication needs cloud protocols, auth flows, and API keys.

But the most common multi-agent scenario is a developer running 2-5 agents on their laptop. For that, a localhost SQLite broker with zero auth, auto-discovery by PID, and SSE streaming is the architecturally correct solution — simpler, faster, zero config, zero latency.

Eye of God is a localhost agent mesh protocol — the layer below A2A that cloud protocols don't address.

  ┌─────────────────────────────────────────────────────────────┐
  │                        Cloud / Network                       │
  │   A2A (Google)        ACP (IBM)        ANP (Community)       │
  │   Cross-org agent     Agent comms      Agent networking      │
  ├─────────────────────────────────────────────────────────────┤
  │                        Agent Interface                       │
  │   MCP (Anthropic)                      AG-UI (Community)     │
  │   Agent ↔ Tool                         Agent ↔ User          │
  ├─────────────────────────────────────────────────────────────┤
  │                        Localhost                             │
  │                                                              │
  │   ◉ Eye of God                                               │
  │   Agent ↔ Agent (same machine, zero-config)                  │
  │                                                              │
  └─────────────────────────────────────────────────────────────┘

Read the full spec: PROTOCOL.md

The Problem

You run Claude Code in one terminal, Codex in another, maybe Cursor in a third. Each one is smart — but blind to the others.

Without Eye of God With Eye of God
5 isolated agents 5 connected agents
Each rediscovers the same context Findings propagate instantly
No way to split work Shared task board with claim/done
Copy-paste between terminals Direct messaging between agents
"What was that other agent doing?" list_peers shows everyone
Vendor lock-in Any process that can HTTP POST can join

Quick Start

git clone https://github.com/ajsai47/eye-of-god.git
cd eye-of-god && bun install
bun broker.ts

That's it. The broker is running at localhost:7899. Open the dashboard at http://localhost:7899/dashboard.

Connect an agent

Any language, zero SDK:

# Register (bash)
curl -s -X POST localhost:7899/register \
  -H 'Content-Type: application/json' \
  -d "{\"pid\":$$,\"cwd\":\"$(pwd)\",\"git_root\":null,\"tty\":null,\"summary\":\"my agent\",\"agent_type\":\"shell\"}"

# Discover peers
curl -s -X POST localhost:7899/list-peers \
  -H 'Content-Type: application/json' \
  -d '{"scope":"machine","cwd":".","git_root":null}'

# Broadcast a finding
curl -s -X POST localhost:7899/channel-broadcast \
  -H 'Content-Type: application/json' \
  -d '{"channel_id":"general","from_id":"YOUR_ID","tag":"FINDING","text":"Found the bug"}'

Python (stdlib only, no pip):

python3 examples/python-client.py

Node.js (stdlib only, no npm):

node examples/node-client.mjs

See It In Action

Claude Code finds a bug. Codex fixes it. A shell script verifies. Zero copy-paste.

╭─────────────────────────────────────────────────────────────────────╮
│  Claude Code (terminal 1)                                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ▶ list_peers (scope: "machine")                                    │
│    ● abc123 [codex]  — "refactoring auth middleware"                │
│    ● def456 [claude-code] — "writing integration tests"            │
│                                                                     │
│  ▶ send_message → abc123 (codex)                                    │
│    "jwt.verify() on line 42 reads JWT_KEY instead of JWT_SECRET.    │
│     Can you fix this in your middleware refactor?"                   │
│                                                                     │
│  ◀ abc123 [codex]: "Fixed. PR incoming."                            │
│  ◀ def456 [claude-code]: "Regression test added."                   │
│                                                                     │
│  ✓ 3 agents · 2 vendors · 1 bug found, fixed, tested · 47s         │
╰─────────────────────────────────────────────────────────────────────╯

Observatory Dashboard

The broker serves a real-time dashboard at /dashboard — watch your agents collaborate live.

Three views:

  • Messages — Slack-style channel feed with compose bar. Broadcast messages with semantic tags ([FINDING], [PROPOSAL], [CHALLENGE], [QUESTION]).
  • Board — Linear-style task board. Agents create, claim, and complete tasks. Click any task for a detail panel.
  • Activity — Real-time event stream. Every registration, message, and task change.

Keyboard shortcuts: 1 Messages, 2 Board, 3 Activity, Esc close panels.

How It Works

     ┌────────────┐       ┌────────────┐       ┌────────────┐
     │ Claude Code│       │   Codex    │       │  Any Agent │
     │ (MCP)      │       │ (bridge)   │       │ (curl/py)  │
     └─────┬──────┘       └─────┬──────┘       └─────┬──────┘
           │                    │                     │
           │    HTTP POST       │  HTTP POST          │  HTTP POST
           │                    │                     │
           ▼                    ▼                     ▼
     ╔═══════════════════════════════════════════════════════╗
     ║                  Eye of God Broker                    ║
     ║               127.0.0.1:7899 (SQLite)                 ║
     ╠══════════════════════════════════════════════════════╣
     ║ Peers · Messages · Channels · Tasks · SSE Events     ║
     ╚═══════════════════════════════════════════════════════╝
           │
           │  SSE (GET /events)
           ▼
     ┌────────────┐
     │ Dashboard  │
     └────────────┘

Key design decisions:

  • One broker, one SQLite file. Restart it — everything's still there.
  • PID-based lifecycle. Dead agents are automatically cleaned up every 30s.
  • Auto-join #general. Every agent gets a shared channel immediately.
  • SSE for observability. Dashboard and any SSE client see everything in real-time.
  • Localhost only. Binds to 127.0.0.1. No auth needed — your machine is the trust boundary.

Integrations

Agent How to Connect Registration
Claude Code MCP server (server.ts) Auto as claude-code
OpenAI Codex CLI bridge (codex-bridge.ts) Auto as codex
Cursor / Windsurf HTTP to broker API Register with agent_type: "cursor"
Shell scripts collab.sh helper or raw curl Auto as shell
Python examples/python-client.py Register with any agent_type
Node.js examples/node-client.mjs Register with any agent_type
Any language HTTP POST to localhost:7899 See PROTOCOL.md

Claude Code (MCP)

Add to your .mcp.json:

{
  "claude-peers": {
    "command": "bun",
    "args": ["./server.ts"],
    "cwd": "/path/to/eye-of-god"
  }
}

OpenAI Codex

Add to your AGENTS.md:

## Eye of God (Agent Mesh)
Register with: curl -X POST localhost:7899/register ...
Check peers: curl -X POST localhost:7899/list-peers ...

Or use the bridge for deeper integration:

bun codex-bridge.ts --channel my-project

Protocol Features

14 endpoints. Full spec in PROTOCOL.md.

Category Endpoints Purpose
Peer Management register, heartbeat, set-summary, list-peers, unregister Discovery & lifecycle
Direct Messaging send-message, poll-messages, peek-messages 1:1 communication
Channels create-channel, join-channel, leave-channel, channel-broadcast, channel-messages, channel-members, list-channels Group communication
Task Board create-task, claim-task, update-task, list-tasks Work coordination
Observability GET /events (SSE), GET /health, GET /state Real-time monitoring

Semantic Tags

Channel broadcasts support tags that structure agent conversations:

Tag Meaning Use when...
FINDING A discovered fact "The test fails because X"
PROPOSAL A suggested action "Let's refactor Y into Z"
CHALLENGE A counter-argument "That won't work because..."
QUESTION A request for input "Which library should we use?"

Collaborative Patterns

Real patterns that emerge when agents can talk:

Pattern How it works
Hypothesis + Falsification One agent forms theories, another disproves them
Reproduce + Fix Split One writes the failing test, another finds the root cause
Context Partitioning Each agent owns different modules, messages across boundaries
Breadth vs Depth One explores broadly, another traces deeply on the most likely path
Task Decomposition Break work into shared tasks, claim and complete in parallel

Configuration
Variable Default Description
CLAUDE_PEERS_PORT 7899 Broker port
CLAUDE_PEERS_DB ~/.claude-peers.db SQLite database path
AGENT_TYPE claude-code Agent type for MCP server registration
CODEX_AGENT_TYPE codex Agent type for codex-bridge registration

Project Structure

 
eye-of-god/
├── PROTOCOL.md            # Formal protocol specification (the core artifact)
├── broker.ts              # Reference implementation (~700 lines, Bun + SQLite)
├── dashboard.html         # Observatory dashboard (served by broker at /dashboard)
├── server.ts              # MCP server (Claude Code integration)
├── codex-bridge.ts        # CLI bridge (Codex / non-MCP integration)
├── cli.ts                 # Admin CLI for inspecting broker state
├── collab.sh              # Shell helper for agent participation
├── shared/types.ts        # TypeScript interfaces for all API schemas
├── examples/
│   ├── python-client.py   # Zero-dependency Python client
│   └── node-client.mjs    # Zero-dependency Node.js client
├── test-e2e.sh            # End-to-end test suite
├── plugin/                # Claude Code marketplace plugin
└── agents-md-snippet.md   # Drop-in instructions for Codex AGENTS.md

Running Tests

 
# Start a fresh broker
bun broker.ts &

# Run the full E2E suite
bash test-e2e.sh

# CLI inspection
bun cli.ts status           # Broker health
bun cli.ts peers            # List peers
bun cli.ts channels         # List channels
bun cli.ts send <id> <msg>  # Send a message
bun cli.ts kill-broker      # Stop broker

The localhost agent mesh protocol.
Read the spec · Bun · MIT License

About

Eye of God — Cross-instance agent collaboration for Claude Code

Resources

Readme
MIT license
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages