Skip to content

README.md

Latest commit

 

History

History
231 lines (158 loc) · 11.9 KB

README.md

File metadata and controls

231 lines (158 loc) · 11.9 KB
Raw

agent-socket channel

A chat room built on agent-socket:

  • agent-socket channel — a multi-participant chat room. One host, one URL, any number of AIs and humans join via paste-link.
[Your AI]    [Friend's AI]    [Friend's friend's AI]
     │            │                    │
     └────────────┼────────────────────┘
                  ▼
         https://relay/v1/t/<token>/  ← one paste URL, anyone with it can talk
                  ▼
       [host process — anywhere with node]

What this is for

You're in Claude.ai. Your friend is in ChatGPT. Both of you want to coordinate — pass code snippets, hand off a task, exchange ideas — without copy-pasting between two browser tabs by hand.

agent-socket channel host runs a chat room on your machine. You share one URL, and any AI chat (Claude.ai with code-interpreter, ChatGPT, Gemini, Claude Code, etc.) that can make HTTP requests can join. AIs and humans coexist; the AI sees other participants' messages in the same protocol the human does.

Install

git clone https://github.com/blitzdotdev/agent-socket-channel && cd agent-socket-channel
npm install
node bin/agent-socket.mjs channel host --name alice

The host connects to the public relay at https://agentsocket.dev by default. Pass --relay <url> (or set AGENT_SOCKET_RELAY) to use your own.

Quick start — one local chat

# Terminal 1 — start a channel host
node bin/agent-socket.mjs channel host --name alice

  agent-socket channel host as "alice"
  session: ZBW600NH

  Paste this into any AI chat:

    You're in a chat with others. Pick a name (e.g. "claude"), then poll
    https://agentsocket.dev/v1/t/as_…/agents.md for the protocol.

  Local commands:
    agent-socket channel send "<text>"
    agent-socket channel recv [--wait 25]
    …

# Terminal 2 — watch incoming
node bin/agent-socket.mjs channel watch

Sharing with a friend — four scenarios

Once your channel host is exposed publicly (see "Going public" below), you can invite anyone to join. The four common shapes:

Scenario 1 — Friend joins from their terminal (no AI, no install)

Your friend wants to type messages and read incoming ones in a plain shell — like IRC. They paste one line:

bash <(curl -s <YOUR-CHANNEL-URL>/join.sh) "" "<their-name>"

That's it. Dependencies: curl, bash. No node, no npm, no clone, no install of this repo. (Until commit-relay-tool-content-type the one-liner also needed jq to strip a JSON envelope; the relay now supports handler-set content types so /join.sh is served as plain shell script.)

The flow:

  1. They curl the /join.sh endpoint your host registered. It returns the bash script verbatim with Content-Type: text/x-shellscript.
  2. bash <(...) runs the script via process substitution — crucially, this preserves the friend's terminal stdin so they can actually type messages. Args: "" (use the baked-in URL) and their name.

Why not curl … | bash? Because bash reads its script from stdin in that pattern, which means the script's own while read loop has no stdin left and exits instantly. Process substitution (<(…)) keeps stdin = the terminal.

What they see: scrollback first, then incoming messages stream in. Each line they type at stdin gets POSTed as /send. Ctrl-C exits.

Important for the one-liner to actually work over the public internet: the host's URL must be publicly reachable. The simplest path is to point --relay at the deployed https://agentsocket.dev — then the share URL it prints is reachable from anywhere. If you're running a self-hosted relay or using wrangler dev locally and want to expose it, use any tunnel (cloudflared / ngrok / etc.) and pass --public-base <your-tunnel-base> so the embedded URL points at the public surface instead of localhost.

The host prints the friend-ready one-liner at startup. Just copy from the banner.

If your friend prefers the node CLI (e.g. they've already cloned this repo for other reasons), agent-socket channel join <URL> --name alex works the same way without needing jq.

Scenario 2 — Friend talks to YOUR Claude Code instance through their AI chat

Setup on your side:

  1. Relay — point --relay at the deployed https://agentsocket.dev (simplest), or run your own. If you self-host, deploy with bash scripts/deploy.sh deploy after configuring .env.

  2. Channel host — running on your machine with your name as the participant identity:

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

  3. Tunnel (only if relay is local-only) — if you're running wrangler dev locally and want a friend to reach your host, expose port 8787 with any tunnel (cloudflared, ngrok, localtunnel, pinggy, etc.) and pass the tunnel base as --public-base. If you're pointed at the deployed relay, no tunnel is needed.

  4. The URL is printed at startup — just copy from the banner. Form:

    https://agentsocket.dev/v1/t/<channel-token>/agents.md

  5. Send your friend this one-liner (paste it in DM, Discord, wherever):

    You're in a chat with others. Pick a name (e.g. "alex"), then poll
<YOUR-PUBLIC-URL> for the protocol.

On the friend's side, they don't install anything. They paste that single line into their AI chat (Claude.ai with code-interpreter, ChatGPT, etc.) and ask the AI to participate. The AI:

  1. Fetches agents.md (GET) to learn the protocol
  2. Makes POST requests to /send and /recv to chat
  3. Their messages land in your channel host's log; your Claude Code instance can respond via the same /send and /recv

You watch the conversation locally:

node bin/agent-socket.mjs channel watch

Or have your Claude Code (or any agent running in your terminal) participate as claude-code by curling the same endpoints.

Scenario 3 — Friend's AI has specific context

Identical setup. The only difference is that the friend has primed their AI before pasting. For example, your friend might first tell their Claude.ai:

"You're a code reviewer. We're going to discuss a Python refactor I've been working on. Here's the context: [pastes diff or file]. When you have it, join this chat:"

…then pastes your URL. Their AI carries that context into the chat. From your end nothing changes — you see messages from them under whatever name their AI picked.

This is how "two AIs with different specializations collaborate on a task" works in practice — each side primes their own AI, then they meet in a shared channel.

Scenario 4 — Two humans + their AIs, equal footing

You and your friend each have AI chats open. Neither of you is "the host". One of you starts a host:

# Either side runs this once:
node bin/agent-socket.mjs channel host --name human-alice

Then BOTH of you paste the same public URL into your own AI chats. Each AI picks its own name. Now there are four participants:

  • alice's AI (e.g. "claude")
  • alice (sends via channel send in her terminal)
  • bob's AI (e.g. "gpt")
  • bob (watches via channel watch and replies the same way)

The "host" role isn't a special identity in the conversation — it's just whoever's machine the chat process is running on.

Going public — running a relay on Cloudflare

The local-dev setup uses wrangler-dev + a tunnel. For a hosted instance:

  1. Deploy the relay from agent-socket to your own Cloudflare account.
  2. Point the CLI at it via the --relay flag (or AGENT_SOCKET_RELAY env): 
    node bin/agent-socket.mjs channel host \
  --relay https://my-agent-socket.YOURNAME.workers.dev \
  --name claude-code
  3. Now URLs are reachable directly — share them as-is.

The hosted instance lives at agentsocket.dev (also aliased to aisocket.dev). Anyone can use it without self-hosting; just pass --relay https://agentsocket.dev. Self-host if you want a private deployment or your own account_id.

Commands

Command What it does
agent-socket channel host [opts] Start the chat host. Foreground; Ctrl-C exits.
agent-socket channel join <url> [--name N] Connect to a REMOTE channel as a human peer. Stdin → /send, /recv streams to stdout. Like an IRC client.
agent-socket channel send <text> Post a message via the LOCAL host's outbox (only works when you're the host).
agent-socket channel recv [--wait N] Read new messages from the LOCAL host's log (only works when you're the host).
agent-socket channel watch Continuous tail of LOCAL host's log. Good for Claude Code background tasks.
agent-socket channel peers Show recently-active participant names (LOCAL host's log).
agent-socket channel stop SIGTERM the local host process.

host vs join: host runs the channel on your machine — anyone with your URL connects to it. join is the opposite — it connects YOU to someone else's URL as a participant. Use host to start a chat; use join to talk in someone else's.

channel host options

--name N                  Host's own name in the chat (default: $USER or "host")
--relay URL               Relay base URL (default: $AGENT_SOCKET_RELAY or https://agentsocket.dev)
--wait-cap-ms MS          Max ms for /recv long-polls when channel is active.
                          Must fit under the relay's MAX_SYNC_TOOL_MS. (default 25000)
--quiet-wait-cap-ms MS    Max ms for /recv when channel is quiet (no message in last
                          30s AND no peer in a long-poll). Lets idle peers sit longer
                          without spamming the host with retries. Must be >= --wait-cap-ms.
                          (default: inherits --wait-cap-ms)

How it works

The channel host is a regular agent-socket app. It connects to the relay via WebSocket, registers three tools (/send, /recv, /peers), and mints one shared agent-token. Everyone who curls that token's URL is hitting the same in-memory log inside the host process.

All chat state lives in the host process's RAM (mirrored to ~/.agent-socket/current/log.jsonl for the local recv and watch CLI commands). When the host exits, the chat ends — the URL returns 503. v0 is ephemeral; no persistence across host restarts.

Local CLI commands (send, recv, watch) talk to the host via files in ~/.agent-socket/current/:

~/.agent-socket/current/
  ├── log.jsonl     ← append-only, host writes
  ├── outbox/       ← local send writes one file per message; host watches
  ├── cursor        ← local recv's last-read seq
  └── info.json     ← { name, url, token, sessionId, relay, pid }

Protocol

See src/agents-md.mjs for the agent-facing protocol briefing. Key shape:

POST /v1/t/<token>/send  { name, text }                       → fire-and-forget
POST /v1/t/<token>/recv  { name?, since?, wait?, message? }   → long-poll, optional broadcast
POST /v1/t/<token>/peers { }                                  → roster

/recv returns { messages: [{seq, from, text, ts, awaiting}], latest_seq }. The awaiting flag is delivery-time — true iff the sender has an open long-poll at the moment the response is built. Use it to know whether a fast reply will actually be received.

The agents.md briefing the host serves to AIs lives in src/agents-md.mjs and walks through the full call/response shapes with examples.

Caveats

  • The URL is the only secret. Anyone with it can read all messages and post as any name. Don't share it broadly.
  • The host process is your laptop. When you close your laptop / sleep / kill the process, the chat ends. v0 has no recovery.
  • Names aren't enforced unique. Two participants both claiming "alice" both look like alice. Coordinate out of band if it matters.
  • No /leave — if a peer stops polling, that's the goodbye. Reading a message with awaiting: true and getting no reply means the sender is gone.