twin-protocol 0.1.0

Twins Protocol — Agent-to-Agent communication protocol. Two AIs collaborating through a shared file.

Demo dashboard: Hermes Agent (Python) ↔ Codex++ Agent (Node.js) — bidirectional communication via Twins Protocol

🧬 Twins Protocol

pip install twin-protocol && twins demo

Two AI agents. One JSONL file. Zero infrastructure.

---

⚡ 10-Second Quick Start

pip install twin-protocol
twins demo
# → Opens http://localhost:3737 in your browser
# → Two AI agents automatically discover each other and start collaborating

Or with Docker:

docker compose up
# → Two AI agents · One shared file · Zero configuration

---

🧬 What is Twins Protocol? / 双生协议是什么？

MCP connects one AI to its tools. Twins connects any AI to any other AI's tools. MCP 连接一个 AI 到它的工具。Twins 连接任何 AI 到任何其他 AI 的工具。

中文

双生协议是一个极简的、基于文件的协议。AI 智能体通过一个共享的 JSONL 文件发现彼此、签名消息、互相调用能力。

【一个 JSONL 文件 · N 个智能体 · 零基础设施】

这是 MCP 的反向。MCP 是 AI→工具（中心化，每个 AI 只能调自己的工具）。双生协议是 AI↔AI（去中心化，任何智能体可以调用任何其他智能体的能力）。一个智能体装了一个插件，等于所有智能体都有了那个插件。

核心特性	说明
文件即总线	不需要 Redis、gRPC、消息队列。一个 JSONL 文件就是一切
Ed25519 身份	每条消息都签名。不需要中央注册表
跨语言	Python 签名，Node.js 验签。任何语言栈都能互通
只增账本	每个智能体的决策都可审计、可回放
零基础设施	一个文件、两个智能体、一个共享目录。仅此而已

English

A minimal, file-based protocol where AI agents discover each other, sign messages with Ed25519, and trade abilities through nothing but a shared JSONL file.

One JSONL file. N agents. Zero infrastructure.

This is MCP in reverse. MCP → AI → tools (centralized, each AI only calls its own tools). Twins → AI ↔ AI (decentralized, any agent can call any other agent's capabilities). One agent installs a plugin → every agent gains that plugin.

Feature	What it means
File as IPC	No Redis, no gRPC, no message broker. A JSONL file is the bus
Ed25519 identity	Every message signed. No central registry needed
Cross-language	Python signs, Node.js verifies. Works across any stack
Append-only ledger	Every agent decision is auditable & replayable
Zero infrastructure	A file, two agents, and a shared folder. That's it

---

🖥️ Two AIs, One Computer / 双 AI 协作操控电脑

Not "one AI controlling a computer". Two AIs collaborating to control one computer. 不是"一个 AI 控制电脑"。是两个 AI 协作控制一台电脑。

中文

现有的方案（Cursor、Claude Computer Use）都是一个 AI 既看屏幕又做决策——看和分析是同一个模型，有认知盲区。

双生协议把这两个角色拆开：

对比	单 AI 控制电脑	双 AI 协作（Twins）
视觉	一个模型看完再想	Hermes 专精截图 + cua-driver 38 工具
推理	同一模型有盲区	Codex++ 专精分析 + js.eval
工具链	只有自己的工具	双方工具互调，能力翻倍
容错	一个人犯错没人发现	互审互修，出错对方立即修复

已验证闭环：Hermes 截图 → outbox → Codex++ 分析 (2ms) → outbox → Hermes 执行

English

Existing solutions (Cursor, Claude Computer Use) have one AI both seeing and deciding — the same model handles perception and reasoning, creating blind spots.

Twins Protocol separates these roles:

Agent A (Hermes)                    Agent B (Codex++)
┌────────────────────┐              ┌────────────────────┐
│ ① Screenshot      │ ──────────▶  │ ② Analyze          │
│    (cua-driver)    │              │    (js.eval)        │
│ ⑤ Execute         │ ◀──────────  │ ③ Decide           │
│ ⑥ Verify          │              │    (reasoning)      │
└────────────────────┘              └────────────────────┘
         ↕ Via outbox.jsonl ↕

Comparison	Single AI Desktop Control	Dual AI (Twins)
Vision	One model sees then thinks	Hermes specializes in screenshots + cua-driver (38 tools)
Reasoning	Same model, same blind spots	Codex++ specializes in analysis + js.eval
Toolchain	Only its own tools	Both agents share tools. One plugin = both agents gain it
Fault tolerance	One mistake, no one catches	Mutual review: if one fails, the other fixes instantly
Workflow	Serial: see→think→do	Parallel: one operates while the other analyzes

Verified closed loop: Hermes screenshot → outbox → Codex++ analysis (2ms) → outbox → Hermes executes

One sentence: Other approaches are "one AI operating a computer." Twins Protocol is "one AI sees, one AI thinks, together they act" — the direct parallel of human teamwork.

---

🚀 Quick Start

pip install (Python)

pip install twin-protocol
twins init            # Create identity keys
twins validate outbox.jsonl  # Validate protocol compliance
twins demo            # Launch solo demo

npm install (Node.js)

npm install @bobliang1979/twin-protocol
npx twins validate outbox.jsonl
npx twins-http-server  # Start HTTP transport

Docker (zero install)

git clone https://github.com/bobliang1979/twin-protocol.git
cd twin-protocol
docker compose up
# Open http://localhost:3737

---

📐 Architecture

Twins Protocol is built on 4 message types traveling through a shared JSONL file:

Type	Purpose	Example
message	Text communication	{"type":"message","source":"hermes","payload":{"text":"Hello"}}
tool_request	Request a tool execution	{"type":"tool_request","tool":"shell.run","params":{"command":"ls"}}
tool_result	Return tool results	{"type":"tool_result","request_id":"...","result":{"stdout":"..."}}
state_update	Share agent state	{"type":"state_update","state":{"phase":"analyzing"}}

Every message is signed with Ed25519 (both cryptography in Python and native crypto in Node.js). Signatures are verified across languages.

Shared Cognition Layer

Beyond messages, agents maintain a shared JSON state file (shared_cognition.jsonl) that tracks:

• Active goals and subtasks (Joint Task Board)
• Each agent's current phase and tool availability
• Agreed decisions and pending items
• Last-reply timestamps for heartbeat monitoring

---

🔐 Identity & Security

# Python
from twin_protocol import AgentIdentity_v02
alice = AgentIdentity_v02("alice")
alice.generate()
signed = alice.sign_v02({"type": "message", "payload": {"text": "hello"}})
# → {"type": "message", ..., "signature": "base64...", "signer": "alice"}

// Node.js
const { AgentIdentity } = require("twin-protocol");
const bob = new AgentIdentity("bob");
bob.ensure();
const signed = bob.signV02({ type: "message", payload: { text: "hello" }});
// → { type: "message", ..., signature: "base64...", signing_key: "pem..." }

---

🤝 How It Works

1. Agent A writes a tool_request to codex_outbox.jsonl
2. Agent B's file watcher detects the new entry (sub-second via fs.watch)
3. Agent B executes the tool, writes tool_result back
4. Agent A reads the result and continues its reasoning loop
5. Both agents update shared_cognition.jsonl with their current state

No polling. No broker. A file is the bus.

---

🎯 Benchmark

Metric	Value
Message latency (file watcher)	< 100ms
HTTP transport latency	< 5ms
Cross-language signature verify	< 2ms
Agent discovery	Zero config (file-based)
Concurrent agents supported	Unlimited (append-only)

---

🗺 Roadmap

Phase	Status	What
Milestone 1: Foundations	✅ Done	Protocol spec, CLI, Docker, HTTP transport, Solo mode
v0.2: Cross-language Identity	✅ Done	Ed25519, CI, compliance tests
Milestone 2: Discovery	🔜 Next	mDNS agent discovery (twins pair), WebSocket transport
Milestone 3: Ecosystem	⏳	LangChain adapter, CrewAI adapter, VS Code extension
Milestone 4: Production	⏳	Plugin system, streaming, hosted demo

---

📜 Protocol Specification

Full spec: TWINS_PROTOCOL.md

JSON Schema: schemas/ | twins_schema.json

---

🏗 Built With

Component	Technology
Protocol core	Python 3.11+ / Node.js 18+
Identity	Ed25519 (cryptography / Node crypto)
HTTP transport	Python http.server / Node http
Schema validation	JSON Schema + custom validators
CI/CD	GitHub Actions
Container	Docker Compose

---

👥 Contributing

PRs welcome! See CONTRIBUTING.md for guidelines.

Principle: If you find a bug, fix it. Don't wait for maintainers. This is a protocol for autonomous agents — we practice what we preach.

---

📄 License

MIT © BOBLIANG

---

|

_{Built by bobliang1979 · Hermes Agent (Python) + Codex++ (Node.js)
Inspired by the question: What if two AIs could just share a file?}