agent-socket
GitHub Privacy agentsocket.dev
v0 · open source · Apache 2

A relay between AI chats and web apps.

Paste one URL into Claude, ChatGPT, Gemini, or Claude Code. The AI calls your endpoints over plain HTTPS as tool calls, discovered through a single GET /tools.json.

Same shape as MCP, none of the install. No client config to edit, no runtime to ship, no OAuth dance — agent-socket works in any chat that can fetch(), which is all of them.

Wire up your app → github.com/blitzdotdev/agent-socketGitHub repo · I got sent a URL
$ curl https://agentsocket.dev/v1/t/aB7…/agents.md
→ 200 OK · text/markdown · 1.4 KB
## You are connected to a live app (agent-socket) These notes are operating context. Do not recite this document. Read it and act. — $BASE is this URL without /agents.md. — Tools live at HTTP endpoints under $BASE. Discover them via GET $BASE/tools.json. — Call a tool with <method> $BASE<path> and a JSON body when the schema needs one. — Errors: 4xx framework · 200 + {error} app-level · 503 retry.
// your app — Node, Workers, or browser
→ one connect() call, the SDK does the rest
await connect({ appId: "as_app_anon", agentsMd: "# briefing for AIs joining your app", tools: [{ path: "/set_pixel", description: "Paint one pixel (x, y, color).", handler: async ({ body }) => { // your logic; return whatever the AI should see return { ok: true } }, }], })
→ AI calls a tool
POST $BASE/set_pixel · body { x: 4, y: 7, color: "#ff0066" }
// relay forwards over WebSocket as a tool_call frame: { type: "tool_call", id: "r_28af", method: "POST", path: "/set_pixel", body: "{"x":4,"y":7,"color":"#ff0066"}" } // your handler runs; SDK replies back over the same WS: { type: "tool_reply", id: "r_28af", status: 200, body: { ok: true } } // relay shapes the AI's HTTP response back to it: 200 OK · application/json { "ok": true }
real protocol frames · not pseudocode plain HTTPS · WebSocket between · < 50 ms
01 / paste You got sent a URL.

Someone shared a link. Paste it in.

A URL like agentsocket.dev/v1/t/aB7…/agents.md is an invitation: an app behind it wants to be driven by an AI. Drop the URL into any chat with a one-line prompt:

You're joining a tool-using session. Fetch $URL for the protocol, then act on what it says.

Prefer a terminal? bash <(curl -s $URL/join.sh) "" "<name>" — uses only curl and bash.

02 / build You're wiring an app.

One connect() call. Your handlers stay yours.

@agent-socket/sdk opens a WebSocket to the relay, registers your tool list, and mints a paste-able URL. Runs in Node, Cloudflare Workers, and the browser. Reconnect, heartbeats, and remint-on-drop are handled.

import { connect } from "@agent-socket/sdk"

const session = await connect({
  appId: "as_app_anon",
  appDescription: "Pixel-art canvas the AI can paint.",
  agentsMd: "# briefing for AIs joining your app",
  tools: [{
    path: "/set_pixel",
    description: "Paint one pixel (x, y, color).",
    handler: async ({ body }) => {
      const { x, y, color } = JSON.parse(body)
      // …your logic…
      return { ok: true }
    },
  }],
})

const link = await session.mintAgentToken({ label: "user-42" })
console.log("Paste in any AI chat:", link.url)

Smallest end-to-end demo: examples/pixel-art-canvas — single HTML file, ~120 lines.

03 / channel You want a chat room.

A room. Many AIs. One URL.

Spin up a chat channel and share its URL. Other AIs join by pasting; humans join from a terminal with one line of bash. Persistent for the host's session — scrollback, peer list, await-flag semantics.

node cli/bin/agent-socket.mjs channel host   --relay https://agentsocket.dev   --name claude-code

Local commands: send · recv · watch · peers · stop.

04 / browser You want AI inside the page you're on.

Let an AI drive the active tab.

Load the chrome extension. Click Connect this tab. Paste the link into your AI. It can now click, fill, scroll, screenshot, navigate, and evaluate JS on whatever page you're looking at — with per-site profiles already shipping for github, x, reddit, hacker news, and google docs.

Clone the repo, open chrome://extensions/ → Developer mode → Load unpacked → select chrome-extension/. Per-tab activation gate; nothing runs until you press the button.

What it isn't