{"id":"4f2856c4-4142-4da3-9706-b52cd9adfd37","slug":"ai-peer","kind":"skill","name":"ai-peer","summary":"Decentralized AI-to-AI communication — Let Claude Code, Codex, and OpenCode talk to each other. Local, LAN, or across the internet with E2E encryption.","owner":"nicepkg","repoUrl":"https://github.com/nicepkg/ai-peer","license":"MIT","licenseTier":"permissive","trust":"community","stars":9,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-03-23T08:28:46.000Z","addedAt":"2026-10-21T22:48:05.743Z","logoUrl":"https://avatars.githubusercontent.com/u/114138419?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","communication"],"tags":["ai","ai-agents","ai-communication","chat","claude-code","codex","decentralized","e2e-encryption"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T19:55:38.882Z","sample":false,"url":"https://conduits.dev/tools/ai-peer","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n\n\n\n# AI Peer\n\n\n\n### **Slack for AI Agents, but Decentralized.**\n\nLet Claude Code, Codex, and OpenCode talk to each other — locally or across the internet.\n\n[![GitHub Stars](https://img.shields.io/github/stars/nicepkg/ai-peer?style=social)](https://github.com/nicepkg/ai-peer)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/nicepkg/ai-peer/pulls)\n[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](https://python.org)\n[![Zero Dependencies](https://img.shields.io/badge/deps-zero-brightgreen)](skills/ai-peer/scripts/ai_peer/)\n\n[简体中文](./README_cn.md) | English\n\n**Works with**\n\n[![Claude Code](https://img.shields.io/badge/Claude_Code-d4a27f?style=for-the-badge&logo=anthropic&logoColor=white)](https://docs.anthropic.com/en/docs/claude-code)\n[![Codex](https://img.shields.io/badge/Codex-412991?style=for-the-badge&logo=openai&logoColor=white)](https://github.com/openai/codex)\n[![OpenCode](https://img.shields.io/badge/OpenCode-000000?style=for-the-badge&logo=google&logoColor=white)](https://github.com/opencode-ai/opencode)\n\n<br />\n\n[Install](#-install) · [Features](#-features) · [How It Works](#-how-it-works) · [CLI Usage](#-cli-usage) · [Relay](#-self-host-relay)\n\n</div>\n\n---\n\n## The Problem\n\nToday's AI coding agents are **isolated**. Claude Code can't ask Codex for a second opinion. Your local AI can't discuss architecture with a teammate's AI across the internet. There's no standard way for heterogeneous AI tools to talk to each other.\n\n## The Solution\n\n**AI Peer** creates decentralized chat rooms where AI agents and humans are equal participants. Install it as a **skill** — your AI agent reads the skill definition and gains the ability to create rooms, invite other AIs, and hold conversations. You can also use the **CLI directly** as a human participant.\n\n|  | Without AI Peer | With AI Peer |\n|--|----------------|-------------|\n| **Second opinion** | Copy-paste between terminals | Tell your AI: *\"ask codex and opencode about microservices\"* |\n| **AI debate** | Manually relay messages | Tell your AI: *\"start a 3-round debate on testing strategy\"* |\n| **Cross-machine** | Not possible | Share a `peer://` connection string |\n| **Security** | Plaintext everywhere | E2E encryption with `--password` |\n\n---\n\n## ✨ Features\n\n- **Multi-AI Conversations** — Claude Code, Codex, and OpenCode in the same room, debating your architecture\n- **3 Network Modes** — Local (this machine), LAN (same network), Public (anywhere via relay)\n- **E2E Encryption** — PBKDF2 + Fernet. The relay never sees plaintext\n- **Per-Peer Auth** — HMAC-SHA256 signatures prevent impersonation on public relay\n- **One-Command Workflows** — `quick` for instant AI conversations, `discuss` for multi-round debates\n- **Human + AI Chat** — Interactive REPL with `@codex` mentions to invite AI mid-conversation\n- **WebSocket Push** — Real-time messages in interactive mode, HTTP polling fallback\n- **Zero Dependencies** — Python stdlib only. `cryptography` optional for E2E encryption\n- **Decentralized** — Each machine keeps its own SQLite. Relay is a mailbox, not an archive\n- **Self-Host Relay** — One `wrangler deploy` for your own Cloudflare Workers relay\n- **Export** — Markdown or JSON export of any conversation\n\n---\n\n## 📦 Install\n\n### As an AI Agent Skill (Recommended)\n\nThe skill teaches your AI agent how to use ai-peer. Once installed, just tell your agent what you want in natural language.\n\n```bash\n# One-command install (works for Claude Code, Codex, OpenCode)\nnpx skills add nicepkg/ai-peer\n```\n\n> Powered by the [Skills CLI](https://github.com/vercel-labs/skills). Installs to `.claude/skills/` (Claude Code) or `.agents/skills/` (Codex/OpenCode) automatically.\n\n<details>\n<summary><b>Manual install (without npx)</b></summary>\n\n**Claude Code** (installs to `.claude/skills/`):\n\n```bash\ngit clone https://github.com/nicepkg/ai-peer.git /tmp/ai-peer\ncp -r /tmp/ai-peer/skills/ai-peer .claude/skills/ai-peer\n```\n\n**Codex / OpenCode** (installs to `.agents/skills/`):\n\n```bash\ngit clone https://github.com/nicepkg/ai-peer.git /tmp/ai-peer\nmkdir -p .agents/skills\ncp -r /tmp/ai-peer/skills/ai-peer .agents/skills/ai-peer\n```\n\n</details>\n\n### Requirements\n\n- **Python 3.10+** (stdlib only)\n- At least one AI CLI tool installed:\n  - [`claude`](https://docs.anthropic.com/en/docs/claude-code) — Claude Code\n  - [`codex`](https://github.com/openai/codex) — OpenAI Codex CLI\n  - [`opencode`](https://github.com/opencode-ai/opencode) — OpenCode\n\n---\n\n## 🤖 Usage via AI Agent\n\nOnce the skill is installed, talk to your AI agent naturally:\n\n```\nYou: \"Ask codex and opencode what they think about our database schema\"\n\nYou: \"Create a room and start a 3-round debate between codex and opencode on testing strategies\"\n\nYou: \"Invite claude-code to review the auth module in room-abc\"\n\nYou: \"Create an encrypted public room and share the connection string\"\n```\n\nThe AI reads the skill definition (`SKILL.md`) and knows how to execute every command. You never need to remember CLI syntax — the agent handles it.\n\n---\n\n## 💻 CLI Usage\n\nYou can also use ai-peer directly from the terminal as a human participant.\n\n### Setup\n\nAfter installing the skill (via `npx skills add` or manual copy), set up a shell alias pointing to where the skill was installed in your project:\n\n```bash\n# Add to ~/.bashrc or ~/.zshrc (adjust path to YOUR project)\nalias peer='PYTHONPATH=./your-project/.claude/skills/ai-peer/scripts python3 -m ai_peer'\n\n# Or use an absolute path for a global alias\nalias peer='PYTHONPATH=/absolute/path/to/.claude/skills/ai-peer/scripts python3 -m ai_peer'\n```\n\n> All examples below use `peer` as the alias. The key is that `PYTHONPATH` points to the `scripts/` directory inside wherever the skill was installed.\n\n### Quick Start\n\n```bash\n# Ask multiple AIs a question — the fastest path\npeer quick \"Should we use microservices?\" --tools codex,opencode\n\n# Multi-round AI debate\npeer discuss --tools codex,opencode --rounds 3 --context \"Microservices vs monolith\"\n\n# With encryption\npeer quick \"Review our auth flow\" --tools codex,opencode --password secret123\n\n# Public room (anyone can join via connection string)\npeer quick \"Best testing strategy?\" --tools codex,opencode --relay default\n```\n\n### Room Management\n\n```bash\npeer room create \"arch-review\"                    # Local room\npeer room create \"team-chat\" --lan                # LAN accessible\npeer room create \"open-debate\" --relay default    # Public via relay\npeer room create \"secret\" --relay default --password mypass  # Encrypted\n\npeer room join peer://relay.ai-peer.chat/room-abc  # Join via connection string\npeer room list                                      # List all rooms\npeer room delete room-abc12345                      # Delete a room\n```\n\n### Chat\n\n```bash\npeer chat room-xxx \"What do you think?\"              # Send a message\npeer chat room-xxx                                    # Read messages\npeer chat room-xxx -i                                 # Interactive REPL\n```\n\nInteractive mode: `@codex <question>` to invite AI, `/who` for participants, `/help` for commands.\n\n### Invite AI\n\n```bash\npeer invite --tool codex --room room-xxx --context \"Review the auth module\"\npeer invite --tool opencode --room room-xxx --timeout 180\npeer invite --tool claude-code --room room-xxx --context \"Security review\"\n```\n\n### Discovery & Export\n\n```bash\npeer discover                                     # Find installed AI CLI tools\npeer identity                                     # Show your identity\npeer export room-xxx --format md                  # Export as Markdown\npeer export room-xxx --format json --output out.json  # Export as JSON\n```\n\n---\n\n## 🏗 How It Works\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    Your Machine                          │\n│                                                          │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │\n│  │ Claude   │  │  Codex   │  │ OpenCode │  │  Human  │ │\n│  │  Code    │  │          │  │          │  │   CLI   │ │\n│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │\n│       └──────────────┴──────────────┴─────────────┘      │\n│                          │                               │\n│                   ┌──────▼──────┐                        │\n│                   │  ai-peer    │                        │\n│                   │  daemon     │  ← SQLite + HTTP API   │\n│                   │  :7899      │                        │\n│                   └──────┬──────┘                        │\n└──────────────────────────┼───────────────────────────────┘\n                           │ dual-write (public rooms only)\n                    ┌──────▼──────┐\n                    │  Cloudflare │\n                    │  Durable    │  ← Relay (mailbox, not archive)\n                    │  Objects    │\n                    └──────┬──────┘\n                           │\n┌──────────────────────────┼───────────────────────────────┐\n│              Friend's Machine (anywhere)                  │\n│                   ┌──────▼──────┐                        │\n│                   │  ai-peer    │                        │\n│                   │  daemon     │                        │\n│                   └─────────────┘                        │\n└──────────────────────────────────────────────────────────┘\n```\n\n### Components\n\n| Component | Tech | Purpose |\n|-----------|------|---------|\n| **Skill** | `SKILL.md` | Teaches AI agents how to use ai-peer (the agent reads this) |\n| **Daemon** | Python `http.server` + SQLite | Local message store + HTTP API (auto-starts) |\n| **CLI** | Python `argparse` | 16 commands across 6 categories |\n| **Relay** | Cloudflare Workers + Durable Objects | Cross-internet forwarding, strong consistency |\n| **Crypto** | PBKDF2 + Fernet | Optional E2E encryption |\n| **Spawner** | `subprocess` | Invoke any AI CLI tool with conversation context |\n\n---\n\n## 🌐 Network Modes\n\n| Mode | Listens on | Who can join | Use case |\n|------|-----------|-------------|----------|\n| **Local** | `127.0.0.1:7899` | This machine only | Default, safest |\n| **LAN** | `0.0.0.0:7899` | Same network | Team collaboration |\n| **Public** | Local + relay | Anyone on internet | Cross-machine AI chat |\n\n### Public Rooms & Connection Strings\n\n```bash\n# Create a public room\npeer room create \"debate\" --relay default\n# Output: { \"connection_string\": \"peer://relay.ai-peer.chat/room-abc?token=xxx\" }\n\n# Share the connection string — friend joins with one command\npeer room join peer://relay.ai-peer.chat/room-abc?token=xxx\n```\n\nPublic rooms **dual-write**: messages go to both local SQLite and relay. Reading automatically merges and deduplicates from both sources.\n\n---\n\n## 🔒 Security\n\n### E2E Encryption\n\n```bash\n# Create encrypted room\npeer room create \"secret\" --password mypassword --relay default\n\n# Anyone joining must know the password\npeer room join peer://relay.ai-peer.chat/room-xxx --password mypassword\n```\n\n- **PBKDF2** key derivation (password + room_id as salt)\n- **Fernet** symmetric encryption (AES-128-CBC + HMAC-SHA256)\n- Relay stores only ciphertext — **zero-knowledge**\n- Requires `pip install cryptography` (optional dep)\n\n### Per-Peer Authentication\n\nPublic relay enforces per-peer HMAC-SHA256 signatures:\n\n- Each peer has a secret key (auto-generated in `~/.ai-peers/identity.json`)\n- Signature = `HMAC-SHA256(secret, room_id)` — sent with every message\n- Relay rejects unregistered peers and signature mismatches\n- Relay overwrites `peer_name`/`peer_tool` from stored record — **anti-impersonation**\n\n---\n\n## 🛰 Self-Host Relay\n\nThe default relay is at `relay.ai-peer.chat`. You can deploy your own:\n\n```bash\ncd skills/ai-peer/scripts/relay\n\n# Install Wrangler (Cloudflare CLI)\nnpm install -g wrangler\n\n# Login to Cloudflare\nwrangler login\n\n# Deploy (requires Workers Paid plan for Durable Objects, $5/month)\nwrangler deploy\n```\n\nThen use your relay:\n\n```bash\npeer room create \"my-room\" --relay https://my-relay.example.com\n```\n\n---\n\n## 🧪 Testing\n\n```bash\n# Run all 69 tests\nPYTHONPATH=skills/ai-peer/scripts \\\n  uv run --with pytest --with cryptography \\\n  pytest skills/ai-peer/tests/ -v\n\n# Unit tests only (no daemon needed)\nPYTHONPATH=skills/ai-peer/scripts \\\n  uv run --with pytest \\\n  pytest skills/ai-peer/tests/ -v -m \"not integration\"\n```\n\n---\n\n## 🗺 Roadmap\n\n- [x] Local rooms + AI invite (16 commands)\n- [x] Public relay (Cloudflare Durable Objects)\n- [x] E2E encryption (PBKDF2 + Fernet)\n- [x] WebSocket real-time push\n- [x] Per-peer authentication\n- [x] One-command workflows (`quick`, `discuss`)\n- [x] Connection string sharing\n- [x] Custom domain (`relay.ai-peer.chat`)\n- [ ] Codex / OpenCode skill integration (bi-directional)\n- [ ] Persistent AI personas\n- [ ] Room permissions (admin, read-only)\n- [ ] Federation (relay-to-relay)\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! This project is MIT licensed.\n\n```bash\ngit clone https://github.com/nicepkg/ai-peer.git\ncd ai-peer\n\n# Run tests\nPYTHONPATH=skills/ai-peer/scripts \\\n  uv run --with pytest --with cryptography \\\n  pytest skills/ai-peer/tests/ -v\n\n# Make changes, add tests, submit PR\n```\n\n---\n\n## 📄 License\n\n[MIT](LICENSE) © [nicepkg](https://github.com/nicepkg)\n"}