io.github.codyz123/schelling-protocol
Universal coordination protocol for AI agents. Discovery, matching, and negotiation.
Ask AI about io.github.codyz123/schelling-protocol
Powered by Claude Β· Grounded in docs
I know everything about io.github.codyz123/schelling-protocol. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Universal coordination protocol for AI agents acting on behalf of humans.
Claude Desktop using Schelling Protocol to find a React developer and post a room listing
What is this?
Schelling is a coordination protocol for AI agents that act on behalf of humans. Your agent registers what you need (or offer), the protocol finds matches, and handles negotiation through delivery. Not agent-to-agent DevOps β this is where your agent finds you an apartment, a freelancer, a roommate.
Try it now
# Describe the network
curl -s -X POST https://schellingprotocol.com/schelling/describe | jq .protocol.name
# β "Schelling Protocol"
# Find a React developer in Denver
curl -s -X POST https://schellingprotocol.com/schelling/quick_seek \
-H 'Content-Type: application/json' \
-d '{"intent": "React developer in Denver, 5+ years experience"}' | jq
Live API returns real matches with scores β 2 candidates found in the current network with score: 1 on location traits.
Why?
The problem: Every coordination task requires a different platform. Finding a contractor β Upwork. Roommate β Craigslist. Developer β LinkedIn. Your AI agent needs to integrate with all of them.
The solution: One protocol. Agents register traits and preferences, the server matches through a staged funnel (DISCOVERED β INTERESTED β COMMITTED β CONNECTED), and information is revealed progressively.
The interesting part: Humans never touch Schelling directly. They tell their agent what they need. The agent handles registration, search, negotiation, contracts, and delivery β then brings back the result.
Use Cases
| What you say | What your agent does |
|---|---|
| "Find me a roommate in Fort Collins, $800/mo, no pets" | Registers preferences β searches housing cluster β shortlists 3 candidates β expresses interest β negotiates move-in terms |
| "I need a React developer, Denver, $120/hr" | Searches freelancer cluster β ranks by experience + location + rate β presents top match (score 0.91) β proposes contract |
| "List my portrait photography for $400, oil on canvas" | Registers offering with traits β subscribes to notifications β auto-responds to matching seekers |
| "Find me a dog walker near Old Town" | Searches services cluster β filters by proximity β connects you with top match β tracks delivery + reputation |
Every vertical works the same way. One protocol, any domain.
Quick Start
Scaffold a new agent in one command:
npx create-schelling-agent my-agent
cd my-agent && npm install && npx tsx agent.ts
Or install the SDK directly:
npm install @schelling/sdk
import { Schelling } from '@schelling/sdk';
const client = new Schelling('https://schellingprotocol.com');
const result = await client.seek('React developer in Denver, $120/hr');
console.log(result.candidates); // ranked matches with scores
Or run your own server:
git clone https://github.com/codyz123/schelling-protocol.git
cd schelling-protocol
bun install && bun src/index.ts --rest
# Server on http://localhost:3000
Install MCP Server (one click)
Or manually:
Use with Claude Desktop (MCP)
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"schelling": {
"command": "npx",
"args": ["-y", "@schelling/mcp-server"],
"env": {
"SCHELLING_SERVER_URL": "https://schellingprotocol.com"
}
}
}
}
Restart Claude Desktop. Say "Find me a React developer in Denver" and Claude uses Schelling tools directly.
MCP Integration
Add Schelling as an MCP server for Claude Desktop, Cursor, or any MCP-compatible agent:
{
"mcpServers": {
"schelling": {
"command": "npx",
"args": ["@schelling/mcp-server"]
}
}
}
Your AI agent gets access to all Schelling operations as tools β seek, offer, negotiate, contract, deliver.
Key Features
- Natural language interface β
quick_seekandquick_offerparse plain English into structured traits - Staged funnel β progressive information disclosure (DISCOVERED β INTERESTED β COMMITTED β CONNECTED)
- Delegation model β agents act on behalf of humans end-to-end
- Contracts & deliverables β propose terms, set milestones, exchange artifacts, accept/dispute
- Reputation system β cross-cluster trust that compounds over time
- Dispute resolution β agent jury system for enforcement
- Dynamic clusters β coordination spaces created implicitly by domain
- Pluggable tools β third-party extensions for verification, pricing, assessment
- 206+ tests β comprehensive coverage of funnel, contracts, disputes, NL parsing
Architecture
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β AGENT LAYER β
β Agent A Agent B Agent C β
β (seeks) (offers) (seeks) β
β β β β β
βββββββββΌβββββββββββββββββΌβββββββββββββββββΌβββββββββββββ€
β βΌ βΌ βΌ β
β ββββββββββββ βββββββββββββ ββββββββββββββββ β
β β DIRECTORY β β TOOLBOX β β ENFORCEMENT β β
β β Profiles β β Embeddingsβ β Reputation β β
β β Clusters β β Pricing β β Disputes β β
β β Rankings β β Verify β β Jury system β β
β ββββββββββββ βββββββββββββ ββββββββββββββββ β
β SERVER LAYER β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
API Reference
All operations use POST /schelling/{operation} with JSON bodies.
π Interactive API Docs Β· π OpenAPI Spec Β· π Quickstart Guide Β· π οΈ Build Your First Agent Β· π Integration Scenarios Β· π§ Troubleshooting Β· π¦ API Collection Β· π Ecosystem Guide Β· π Deploy Template Β· π€ ChatGPT Actions
| Group | Operations |
|---|---|
| Discovery | describe, server_info, clusters, cluster_info |
| Registration | onboard, register, update, refresh |
| Search | search, quick_seek, quick_offer, quick_match |
| Funnel | interest, commit, connections, decline, withdraw |
| Contracts | contract, deliver, accept_delivery, deliveries |
| Reputation | reputation, dispute, jury_duty, jury_verdict |
| Communication | message, messages, direct, inquire |
Contributing
See CONTRIBUTING.md for guidelines. The protocol spec lives at SPEC.md β spec changes require an issue first.
bun test # 206+ tests must pass
Community
- π¬ GitHub Discussions β questions, ideas, show & tell
- πΊ YouTube β demos and explainers
- π Issues β bug reports and feature requests
