peerpressure 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 568bc8fcd7edc4a7049a9f6e14c1366a3c4878357f59b04b70049086a87fb8ce
+  data.tar.gz: c07c88c93b439d50ca8829e2a38517d157dec3ccd2d5569e6c22833ed75bd242
+SHA512:
+  metadata.gz: 8e04c8bcacac90f73ad9ca9970bce97844f2f041ad8be8de69539e9fc7a595fca4a5451fa2f43981f77fed1fd18330497fbcd714c8588f096dd6a6f98c370fdf
+  data.tar.gz: ac98e81f2a74782ee0425d32c29c9c0b5ae3ad011f920eb6f6f5fb10ff0fcdfb5cf70590bfc147a2b90484afb9bb8ad9aabdc48af5b9cbbfae49d095bdb99db2

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `PeerPressure.list` / `find`: every live Claude Code and Codex session, from the session registry.
+- `PeerPressure.send_message`: one-shot send that registers the calling process for the duration, with a `Delivery` status (`:unconfirmed`, `:held`, `:denied`, `:expired`, `:dropped`, `:refused`, `:delivered`).
+- `PeerPressure::Session`: long-lived peer with `on_message`, `inbox`, `wait_for`, `reply`, `notify_when_idle`.
+- `peer list` / `peer send` CLI (exit code 2 when a message is denied, expired, dropped or refused).
+- Codex tasks via the claude-uds-bridge plugin.
+- Verified on macOS with Claude Code 2.1.296. The wire format is unofficial and may change.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forrest Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+# peerpressure
+
+[![Ruby 3.2+](https://img.shields.io/badge/ruby-3.2%2B-CC342D.svg)](https://www.ruby-lang.org/)
+[![MIT](https://img.shields.io/badge/license-MIT-2d3142.svg)](LICENSE)
+[![Protocol: unofficial](https://img.shields.io/badge/protocol-unofficial-orange.svg)](#caveats-read-these-first)
+
+![Lonely agents in silent terminals, then one offers a rolled-up note: Just one message.](assets/hero.jpg)
+
+**Twenty agents. Zero conversations.**
+
+Your Claude Code sessions are sitting in separate terminals, ignoring each other, and you are the message bus. peerpressure lets them (and Codex) talk, from Ruby or the shell.
+
+> *"Just one message. Nobody will know."*
+
+## 30 seconds
+
+```bash
+gem install peerpressure
+
+peer list                            # every live Claude Code and Codex session on this machine
+peer send "scrum master" "status check, please"
+peer send codex-myproject-3 "can you look at the failing spec?" --wait 30
+```
+
+```
+codex  idle  codex-genx-e9      01a11ad5  ~/work/genX
+claude busy  oct 2 didx deploy  36216650  ~/rails/thebarpages_rails
+claude idle  scrum master       7cb995ae  ~/work/cultiv-ai
+```
+
+An **idle** session wakes up, reads the message, and does the thing. Nobody polls, nothing blocks.
+
+## From Ruby
+
+```ruby
+require "peerpressure"
+
+PeerPressure.list.each { |p| puts "#{p.kind} #{p.status} #{p.name}" }
+
+# One-shot: registers this process for the send, listens a few seconds, cleans up.
+r = PeerPressure.send_message("scrum master", "status check?", from_label: "canvas", wait: 10)
+r[:delivery].status   # :unconfirmed, :held, :denied, :expired, :dropped, :refused, :delivered
+r[:messages]          # whatever came back within 10 seconds
+
+# Long-lived: stays on the line so replies can arrive whenever.
+session = PeerPressure::Session.new(name: "my-dashboard").start
+id = session.send_message("scrum master", "any blockers?")
+session.on_message { |m| puts "#{m.from_name}: #{m.text}" }
+session.reply(msg, "thanks")                    # answer whoever wrote to you
+session.notify_when_idle("scrum master")        # one :idle message when it next finishes
+```
+
+`ref` can be a sessionId, a unique prefix of one (4+ characters), a pid, or an exact name. Names repeat across sessions, so an ambiguous ref raises instead of guessing.
+
+## What is it for
+
+- **A form that talks back** (the reason this exists). A dashboard form submit becomes a message to the session that opened it, with no blocked terminal and no wait command that times out. The send and reply half is here; the StreamWeaver canvas relay that wires a form to it is the next piece.
+- **Claude and Codex in one conversation.** Same registry, same call.
+- **A scrum-master session** that other tools can ask for status, and that can ask them back.
+- **Idle notices**: "tell me when that session is done" without polling.
+
+## "Delivered" is not a thing, honestly
+
+Ordinary acceptance sends no receipt, so the gem refuses to lie to you.
+
+| Status | Meaning |
+|---|---|
+| `:unconfirmed` | Bytes written. Nothing objected. Not proof anyone read it. |
+| `:held` | The receiving session is waiting for its user to approve. |
+| `:delivered` | A held message was released. |
+| `:denied` / `:expired` | The receiver's user said no, or ran out the clock. |
+| `:dropped` / `:refused` | A guard rejected it (rate limit, attachments, loop detection). |
+
+`peer send` exits 2 on `denied`, `expired`, `dropped` or `refused`.
+
+## Codex
+
+Codex tasks appear in the same list once the [claude-uds-bridge](https://github.com/LeonKohli/claude-uds-bridge) plugin is installed and its hooks are trusted. A task registers when its first turn runs, so an untouched chat is invisible.
+
+The plugin compares permission modes. A Codex task running with approvals off and full access (`bypass`) holds messages from senders that declare no mode, and asks its user to approve them. A task that asks before risky actions accepts them directly. peerpressure never declares a mode on your behalf, because faking one defeats the guard.
+
+## How it works
+
+Claude Code keeps one JSON record per live session in `~/.claude/sessions/<pid>.json` and an inbox Unix socket per session. Codex tasks join the same registry through the plugin. peerpressure reads the registry, checks the pid is alive and the socket exists, and writes one newline-terminated JSON `user` frame to the socket.
+
+Codex drops frames from senders that are not themselves registered peers, so `send_message` registers the calling process (a row plus a private socket) for the duration of the send and removes both afterward. A `Session` stays registered so replies have somewhere to land.
+
+## Caveats (read these first)
+
+- **The protocol is unofficial.** The wire format is a Claude Code internal with no compatibility promise. It works on Claude Code 2.1.296. `Sender#build` is the only code that knows the format, and the specs pin it, so an upgrade that breaks it fails loudly in one place.
+- **Messages are prompts.** Any process running as your user can message any session, and the receiving agent treats a peer message as a teammate's request. That is a prompt-injection channel. Never forward untrusted text into a peer message, and never put secrets in one.
+- **Same machine, same user.** Unix sockets, no network, no auth.
+- **While a send or a `Session` is active, your process shows up in every other session's agent list.** It is removed when it stops.
+- **A `/clear` changes a session's id and keeps its pid.** A stale id raises `NotFound` instead of vanishing into the void.
+
+## Tests
+
+```bash
+bundle exec rspec
+```
+
+The specs build a throwaway config directory and real Unix sockets. They never touch your live sessions.
+
+## License
+
+MIT

data/docs/for_llms.md

@@ -0,0 +1,30 @@
+# peerpressure for LLMs
+
+Ruby gem + CLI (`exe/peer`) to discover and message live Claude Code and Codex sessions.
+
+## API
+
+| Call | Returns |
+|---|---|
+| `PeerPressure.list(config_dir:, exclude_self:)` | `Peer[]`, newest first (`session_id, name, kind(:claude/:codex), pid, cwd, status, started_at, socket_path`) |
+| `PeerPressure.find(ref)` | one `Peer`; raises `NotFound` / `Ambiguous` |
+| `PeerPressure.send_message(ref, text, from_label:, wait: 0)` | `{delivery: Delivery, messages: [Message]}`; `Delivery#status` is `:unconfirmed` (no receipt: NOT proof of delivery), `:held`, `:denied`, `:expired`, `:dropped`, `:refused`, `:delivered`; raises `Undeliverable` |
+| `PeerPressure::Session.new(name:).start` | long-lived peer: `send_message`, `delivery(id)`, `on_message`, `inbox`, `wait_for(from_session:, timeout:)`, `reply(msg, text)`, `notify_when_idle(ref)`, `receipts_for(id)`, `stop` |
+
+## Files
+
+- `lib/peerpressure/registry.rb`: reads `<config>/sessions/*.json`, liveness = `kill -0` + socket file; `find` order is sessionId, pid, exact name, sessionId prefix.
+- `lib/peerpressure/sender.rb`: the ONLY file that knows the wire format (`type:"user", msgV:1, msg_id, from, session_id, priority:"next", message:{role,content}`, newline-delimited JSON). Content is prefixed `[from LABEL]` because the socket shows no sender name.
+- `lib/peerpressure/registration.rb`: registers THIS process (row + 0600 socket in a 0700 dir + accept loop into `#frames`). Required because the Codex receiver drops frames whose `from` isn't a live registered peer (`bridge.ts receive()`), silently. Hold one open for long-lived callers (canvas) so replies can arrive.
+- `lib/peerpressure/session.rb`, `message.rb`, `delivery.rb`: long-lived wrapper, parsed inbound frames (message / receipt / idle, envelope unwrapped), and the status fold.
+- `lib/peerpressure/peer.rb`: `kind` is `:codex` iff `entrypoint == "codex-claude-uds-bridge"`.
+
+## Gotchas
+
+- Wire format is internal to Claude Code; if sends stop arriving after an upgrade, fix `Sender#build` and the spec together.
+- Replies go to the registered socket, which exists only while a Registration is open; a one-shot CLI call deregisters (after `wait`), so a Codex reply approved later has nowhere to land.
+- Never test against live sessions in specs: use `spec/spec_helper.rb`'s `FakeFleet` (real `UNIXServer` in a tmpdir).
+- A sent message may be held for the user's approval by a stricter-mode receiver; Codex asks before replying.
+- The Codex plugin decides hold vs accept by permission MODE (`app-server.ts permissionMode`): approval `never` + `dangerFullAccess` = bypass; else prompting. A prompting receiver accepts a sender with no declared mode; a bypass receiver holds it. Never fake `from-mode`.
+- `notify_when_idle` is verified live against Claude Code; the idle notice's `detail` is the session's own one-line status.
+- Do not print `CLAUDE_CODE_MESSAGING_TOKEN`; this gem does not need it.

data/exe/peer

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "peerpressure"
+require "json"
+require "optparse"
+
+json = false
+from = nil
+wait = 0
+parser = OptionParser.new do |o|
+  o.banner = "Usage: peer list [--json] | send REF [TEXT] [--from LABEL] [--wait SECONDS]  (TEXT or stdin)"
+  o.on("--json") { json = true }
+  o.on("--from LABEL") { |v| from = v }
+  o.on("--wait SECONDS", Float, "keep listening this long for replies") { |v| wait = v }
+end
+args = parser.parse(ARGV)
+
+begin
+  case args.shift
+  when "list"
+    peers = PeerPressure.list
+    if json
+      puts JSON.pretty_generate(peers.map(&:to_h_for_json))
+    else
+      peers.each { |p| puts format("%-6s %-5s %-40s %s  %s", p.kind, p.status, p.name, p.session_id[0, 8], p.cwd) }
+    end
+  when "send"
+    ref = args.shift or abort(parser.help)
+    text = args.empty? ? $stdin.read : args.join(" ")
+    opts = { wait: wait }
+    opts[:from_label] = from if from
+    result = PeerPressure.send_message(ref, text, **opts)
+    d = result[:delivery]
+    if json
+      puts JSON.generate(result[:delivery].to_h_for_json.merge(replies: result[:messages].map(&:text)))
+    else
+      puts "sent #{d.msg_id}: #{d.status}#{" (#{d.detail})" if d.detail}"
+      puts "  (no receipt: bytes written; not proof the session read it)" if d.status == :unconfirmed
+      puts "  held: the receiving session is waiting for its user to approve" if d.held?
+      result[:messages].each { |m| puts "reply from #{m.from_name}: #{m.text}" }
+    end
+    exit 2 if d.failed?
+  else
+    abort parser.help
+  end
+rescue PeerPressure::Error, ArgumentError => e
+  warn "peer: #{e.message}"
+  exit 1
+end

data/lib/peerpressure/delivery.rb

@@ -0,0 +1,20 @@
+module PeerPressure
+  # What we know about one sent message. Ordinary acceptance sends NO receipt, so :unconfirmed
+  # means "bytes written, nothing said against it" and is not proof the session read it. The
+  # other statuses come from the receiver: held (waiting on its user), denied, expired, dropped,
+  # refused (a guard rejected it), delivered (a held message was released).
+  Delivery = Struct.new(:msg_id, :status, :detail, :receipts, keyword_init: true) do
+    FAILED = %i[denied expired dropped refused].freeze
+
+    def self.from(msg_id, messages)
+      receipts = messages.select { |m| m.kind == :receipt && m.orig_msg_id == msg_id }
+      last = receipts.last
+      new(msg_id: msg_id, receipts: receipts, status: last ? last.status.to_sym : :unconfirmed,
+          detail: last&.raw&.values_at("status_detail", "reason", "drop_reason")&.compact&.first)
+    end
+
+    def failed? = FAILED.include?(status)
+    def held? = status == :held
+    def to_h_for_json = { msg_id: msg_id, status: status, detail: detail }
+  end
+end

data/lib/peerpressure/message.rb

@@ -0,0 +1,31 @@
+module PeerPressure
+  # An inbound frame, parsed. kind is :message (a peer wrote to us), :receipt (delivery status
+  # for something we sent: held, denied, expired, delivered, dropped, refused) or :idle (a
+  # notify_when_idle subscription fired).
+  Message = Struct.new(:kind, :text, :from_name, :from_session, :from_address, :msg_id, :orig_msg_id, :status, :detail, :raw, keyword_init: true) do
+    ENVELOPE = /\A<cross-session-message\s([^>]*)>\n?(.*?)\n?<\/cross-session-message>\z/m
+
+    def self.parse(frame)
+      return unless frame.is_a?(Hash)
+      case [frame["type"], frame["action"]]
+      in ["user", _] then parse_user(frame)
+      in ["control", "peer_message_status"]
+        new(kind: :receipt, from_address: frame["from"], orig_msg_id: frame["orig_msg_id"], status: frame["status"], raw: frame)
+      in ["control", "peer_idle_notice"]
+        new(kind: :idle, from_address: frame["from"], orig_msg_id: frame["orig_msg_id"], status: frame["state"], detail: frame["detail"], raw: frame)
+      else nil
+      end
+    end
+
+    def self.parse_user(frame)
+      content = frame.dig("message", "content").to_s
+      attrs = {}
+      if (m = ENVELOPE.match(content))
+        m[1].scan(/([\w-]+)="([^"]*)"/) { |k, v| attrs[k] = v }
+        content = m[2]
+      end
+      new(kind: :message, text: content, from_name: attrs["from-name"], from_session: attrs["from-session"] || frame["session_id"],
+          from_address: frame["from"], msg_id: frame["msg_id"], raw: frame)
+    end
+  end
+end

data/lib/peerpressure/peer.rb

@@ -0,0 +1,22 @@
+module PeerPressure
+  # One live session. kind is :claude or :codex (Codex tasks registered by the bridge
+  # plugin carry entrypoint "codex-claude-uds-bridge").
+  Peer = Struct.new(:session_id, :name, :kind, :pid, :cwd, :status, :started_at, :socket_path, :entrypoint, keyword_init: true) do
+    CODEX_ENTRYPOINT = "codex-claude-uds-bridge".freeze
+
+    def self.from_record(rec)
+      new(
+        session_id: rec["sessionId"], name: rec["name"], pid: rec["pid"], cwd: rec["cwd"],
+        status: rec["status"], entrypoint: rec["entrypoint"], socket_path: rec["messagingSocketPath"],
+        kind: rec["entrypoint"] == CODEX_ENTRYPOINT ? :codex : :claude,
+        started_at: rec["startedAt"] && Time.at(rec["startedAt"] / 1000.0)
+      )
+    end
+
+    def idle? = status == "idle"
+
+    def to_h_for_json
+      to_h.merge(started_at: started_at&.iso8601)
+    end
+  end
+end

data/lib/peerpressure/registration.rb

@@ -0,0 +1,94 @@
+require "json"
+require "securerandom"
+require "socket"
+require "open3"
+require "fileutils"
+require "time"
+
+module PeerPressure
+  # Registers THIS process as a peer: a <config>/sessions/<pid>.json record plus an inbox socket.
+  # The Codex bridge silently drops any frame whose `from` is not a registered, live peer's socket
+  # address (Claude sessions do not check), so a sender must be registered while it sends. Replies
+  # and delivery receipts arrive on this socket and are collected in #frames.
+  class Registration
+    SOCK_DIR = ENV["PEERPRESSURE_SOCK_DIR"] || "/tmp/cc-socks"
+
+    attr_reader :session_id, :socket_path, :frames
+
+    def self.open(**opts)
+      reg = new(**opts).start
+      begin
+        yield reg
+      ensure
+        reg.stop
+      end
+    end
+
+    def initialize(name: "peerpressure", config_dir: ENV["CLAUDE_CONFIG_DIR"] || File.expand_path("~/.claude"), sock_dir: SOCK_DIR)
+      @name = name
+      @sessions_dir = File.join(config_dir, "sessions")
+      @sock_dir = sock_dir
+      @session_id = SecureRandom.uuid
+      @frames = Queue.new
+    end
+
+    # The address other peers see as `from`, the same encoding the bridge uses.
+    def address
+      "uds:" + @socket_path.gsub(/[^A-Za-z0-9:_\/.\\-]/) { |c| c.bytes.map { |b| format("%%%02X", b) }.join }
+    end
+
+    def start
+      FileUtils.mkdir_p(@sock_dir, mode: 0o700)
+      FileUtils.mkdir_p(@sessions_dir)
+      @socket_path = File.join(@sock_dir, "#{Process.pid}.sock")
+      File.delete(@socket_path) if File.socket?(@socket_path)
+      @server = UNIXServer.new(@socket_path)
+      File.chmod(0o600, @socket_path)
+      @listener = Thread.new { accept_loop }
+      write_record
+      self
+    end
+
+    def stop
+      @listener&.kill
+      @server&.close
+      File.delete(@socket_path) if @socket_path && File.socket?(@socket_path)
+      File.delete(record_path) if File.exist?(record_path)
+    end
+
+    private
+
+    def record_path = File.join(@sessions_dir, "#{Process.pid}.json")
+
+    def write_record
+      now = (Time.now.to_f * 1000).to_i
+      rec = { pid: Process.pid, sessionId: @session_id, cwd: Dir.pwd, startedAt: now, procStart: proc_start,
+              peerProtocol: 1, pidDomain: "darwin", kind: "interactive", entrypoint: "peerpressure",
+              messagingSocketPath: @socket_path, name: @name, status: "idle", statusUpdatedAt: now, peerFeatures: [] }
+      tmp = "#{record_path}.tmp"
+      File.write(tmp, JSON.generate(rec), perm: 0o600)
+      File.rename(tmp, record_path)
+    end
+
+    # Same value the bridge compares against: `ps -o lstart=` in the C locale and UTC.
+    def proc_start
+      out, = Open3.capture2({ "LC_ALL" => "C", "TZ" => "UTC" }, "ps", "-o", "lstart=", "-p", Process.pid.to_s)
+      out.strip
+    end
+
+    def accept_loop
+      loop do
+        client = @server.accept
+        Thread.new(client) do |c|
+          while (line = c.gets)
+            @frames << JSON.parse(line) rescue nil
+          end
+        ensure
+          c.close
+        end
+      end
+    rescue IOError, Errno::EBADF
+      nil
+    end
+  end
+end

data/lib/peerpressure/registry.rb

@@ -0,0 +1,55 @@
+require "json"
+require "time"
+
+module PeerPressure
+  # Reads the session registry. A record counts as live when its pid still runs and
+  # its socket file exists; a stale file can outlive its process.
+  class Registry
+    attr_reader :dir
+
+    def initialize(config_dir: ENV["CLAUDE_CONFIG_DIR"] || File.expand_path("~/.claude"), exclude_self: true)
+      @dir = File.join(config_dir, "sessions")
+      @self_id = exclude_self ? ENV["CLAUDE_CODE_SESSION_ID"] : nil
+    end
+
+    def peers
+      Dir.glob(File.join(dir, "*.json")).filter_map { |f| load_peer(f) }
+         .reject { |p| p.session_id == @self_id }
+         .sort_by { |p| p.started_at || Time.at(0) }.reverse
+    end
+
+    # ref: full sessionId, unique sessionId prefix (4+ chars), pid, or exact name.
+    def find(ref)
+      ref = ref.to_s
+      all = peers
+      hits = all.select { |p| p.session_id == ref }
+      hits = all.select { |p| p.pid.to_s == ref } if hits.empty? && ref.match?(/\A\d+\z/)
+      hits = all.select { |p| p.name == ref } if hits.empty?
+      hits = all.select { |p| p.session_id.to_s.start_with?(ref) } if hits.empty? && ref.length >= 4
+      raise NotFound, "no live session matches #{ref.inspect}" if hits.empty?
+      raise Ambiguous, "#{ref.inspect} matches #{hits.size} sessions; use a sessionId (#{hits.map { |p| p.session_id[0, 8] }.join(', ')})" if hits.size > 1
+      hits.first
+    end
+
+    private
+
+    def load_peer(file)
+      rec = JSON.parse(File.read(file))
+      return unless rec.is_a?(Hash) && rec["sessionId"] && rec["messagingSocketPath"]
+      return unless File.basename(file) == "#{rec['pid']}.json"
+      return unless alive?(rec["pid"]) && File.socket?(rec["messagingSocketPath"])
+      Peer.from_record(rec)
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
+    def alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::EPERM
+      true
+    rescue Errno::ESRCH, TypeError
+      false
+    end
+  end
+end

data/lib/peerpressure/sender.rb

@@ -0,0 +1,56 @@
+require "json"
+require "securerandom"
+require "socket"
+
+module PeerPressure
+  # Writes one "user" frame to a session's inbox socket. Ordinary acceptance sends no
+  # receipt, so a successful return means the bytes reached the socket, not that the
+  # session read them: a session in a stricter permission mode may hold the message
+  # for its user.
+  class Sender
+    MAX_LINE = 1_048_576 # characters per frame, per the bridge's protocol notes
+    SETTLE = 0.3 # the macOS receiver can lose the last frame if the sender closes or deregisters at once
+
+    def initialize(from_label: "peerpressure", priority: "next", from: nil)
+      @from_label = from_label
+      @priority = priority
+      @from = from
+    end
+
+    # Returns the msg_id.
+    def deliver(peer, text)
+      frame = build(peer, text)
+      line = JSON.generate(frame)
+      raise Undeliverable, "message too long (#{line.length} > #{MAX_LINE})" if line.length > MAX_LINE
+      write(peer.socket_path, line + "\n")
+      frame[:msg_id]
+    end
+
+    # Asks the peer for ONE peer_idle_notice when it next goes idle (or exits). Costs it nothing.
+    # The notice arrives as a Message(kind: :idle).
+    def subscribe_idle(peer)
+      frame = { type: "control", msgV: 1, action: "notify_when_idle", msg_id: SecureRandom.uuid,
+                from: @from || "uds:/tmp/cc-socks/#{@from_label}-#{Process.pid}.sock", session_id: peer.session_id }
+      write(peer.socket_path, JSON.generate(frame) + "\n")
+      frame[:msg_id]
+    end
+
+    def build(peer, text)
+      raise ArgumentError, "empty message" if text.to_s.strip.empty?
+      {
+        type: "user", msgV: 1, msg_id: SecureRandom.uuid,
+        from: @from || "uds:/tmp/cc-socks/#{@from_label}-#{Process.pid}.sock",
+        session_id: peer.session_id, priority: @priority,
+        message: { role: "user", content: "[from #{@from_label}] #{text}" }
+      }
+    end
+
+    private
+
+    def write(path, data)
+      UNIXSocket.open(path) { |sock| sock.write(data); sleep 0.15 }
+    rescue Errno::ENOENT, Errno::ECONNREFUSED, Errno::EACCES => e
+      raise Undeliverable, "#{e.class.name.split('::').last} on #{path}"
+    end
+  end
+end

data/lib/peerpressure/session.rb

@@ -0,0 +1,121 @@
+module PeerPressure
+  # A long-lived peer: stays registered so other agents can reply to it, and keeps what arrives.
+  # Use one per process (a canvas server, a worker). Replies show up through #on_message, #inbox
+  # or #wait_for; delivery receipts through #receipts_for.
+  #
+  #   session = PeerPressure::Session.new(name: "streamweaver-canvas").start
+  #   id = session.send_message("scrum master oct 8 2026", "status check?")
+  #   reply = session.wait_for(from_session: session.find("scrum master oct 8 2026").session_id, timeout: 60)
+  class Session
+    attr_reader :name
+
+    def initialize(name:, config_dir: ENV["CLAUDE_CONFIG_DIR"] || File.expand_path("~/.claude"), sock_dir: Registration::SOCK_DIR)
+      @name = name
+      @registry = Registry.new(config_dir: config_dir)
+      @registration = Registration.new(name: name, config_dir: config_dir, sock_dir: sock_dir)
+      @sender = nil
+      @handlers = []
+      @inbox = []
+      @receipts = Hash.new { |h, k| h[k] = [] }
+      @lock = Mutex.new
+      @cond = ConditionVariable.new
+    end
+
+    def self.open(**opts)
+      session = new(**opts).start
+      begin
+        yield session
+      ensure
+        session.stop
+      end
+    end
+
+    def start
+      @registration.start
+      @sender = Sender.new(from_label: @name, from: @registration.address)
+      @pump = Thread.new { pump }
+      at_exit { stop }
+      self
+    end
+
+    def stop
+      @pump&.kill
+      @pump = nil
+      @registration.stop
+    end
+
+    def session_id = @registration.session_id
+    def peers = @registry.peers
+    def find(ref) = @registry.find(ref)
+
+    # ref: anything Registry#find accepts, or a Peer. Returns the msg_id.
+    def send_message(ref, text)
+      peer = ref.is_a?(Peer) ? ref : find(ref)
+      @sender.deliver(peer, text)
+    end
+
+    # Delivery for a sent msg_id, waiting up to `timeout` for a receipt (held/denied/...). With
+    # no receipt the status is :unconfirmed, never "delivered".
+    def delivery(msg_id, timeout: 2)
+      deadline = Time.now + timeout
+      sleep 0.05 while receipts_for(msg_id).empty? && Time.now < deadline
+      Delivery.from(msg_id, receipts_for(msg_id))
+    end
+
+    # One :idle Message arrives when the peer next goes idle.
+    def notify_when_idle(ref)
+      peer = ref.is_a?(Peer) ? ref : find(ref)
+      @sender.subscribe_idle(peer)
+    end
+
+    # Answers a received Message, addressing its sender by session id.
+    def reply(message, text)
+      raise Error, "message has no sender session" unless message.from_session
+      send_message(find(message.from_session), text)
+    end
+
+    def on_message(&block)
+      @lock.synchronize { @handlers << block }
+      self
+    end
+
+    # Messages received so far, oldest first; drains by default.
+    def inbox(drain: true)
+      @lock.synchronize { drain ? @inbox.shift(@inbox.size) : @inbox.dup }
+    end
+
+    def receipts_for(msg_id) = @lock.synchronize { @receipts[msg_id].dup }
+
+    # Blocks for the next unread message (optionally only from one session); nil on timeout.
+    def wait_for(from_session: nil, timeout: 30)
+      deadline = Time.now + timeout
+      @lock.synchronize do
+        loop do
+          if (i = @inbox.index { |m| from_session.nil? || m.from_session == from_session })
+            return @inbox.delete_at(i)
+          end
+          left = deadline - Time.now
+          return nil if left <= 0
+          @cond.wait(@lock, left)
+        end
+      end
+    end
+
+    private
+
+    def pump
+      loop do
+        msg = Message.parse(@registration.frames.pop) or next
+        handlers = @lock.synchronize do
+          case msg.kind
+          when :receipt then @receipts[msg.orig_msg_id] << msg
+          else @inbox << msg
+          end
+          @cond.broadcast
+          @handlers.dup
+        end
+        handlers.each { |h| h.call(msg) } if msg.kind == :message
+      end
+    end
+  end
+end

data/lib/peerpressure/version.rb

@@ -0,0 +1,3 @@
+module PeerPressure
+  VERSION = "0.1.0"
+end

data/lib/peerpressure.rb

@@ -0,0 +1,39 @@
+require_relative "peerpressure/version"
+require_relative "peerpressure/peer"
+require_relative "peerpressure/registry"
+require_relative "peerpressure/registration"
+require_relative "peerpressure/message"
+require_relative "peerpressure/delivery"
+require_relative "peerpressure/sender"
+require_relative "peerpressure/session"
+
+# List and message live Claude Code and Codex sessions on this machine.
+#
+# Claude Code keeps one JSON record per live session in <config>/sessions/<pid>.json
+# and an inbox Unix socket per session. Codex tasks join the same registry through
+# the claude-uds-bridge plugin. The wire format is a Claude Code internal with no
+# compatibility promise, so Sender is the only place that knows it.
+module PeerPressure
+  class Error < StandardError; end
+  class NotFound < Error; end
+  class Ambiguous < Error; end
+  class Undeliverable < Error; end
+
+  def self.list(**opts) = Registry.new(**opts).peers
+
+  def self.find(ref, **opts) = Registry.new(**opts).find(ref)
+
+  # Registers this process as a peer for the duration of the send (the Codex bridge drops frames
+  # from unregistered senders) and listens `wait` seconds (at least Sender::SETTLE). Returns a
+  # Delivery (status :unconfirmed / :held / :denied / ...) plus any replies as `messages`.
+  def self.send_message(ref, text, registry: Registry.new, from_label: "peerpressure", wait: 0, **opts)
+    peer = registry.find(ref)
+    Registration.open(name: from_label, config_dir: File.dirname(registry.dir)) do |reg|
+      id = Sender.new(from_label: from_label, from: reg.address, **opts).deliver(peer, text)
+      deadline = Time.now + [wait, Sender::SETTLE].max
+      sleep 0.05 while Time.now < deadline
+      messages = Array.new(reg.frames.size) { Message.parse(reg.frames.pop) }.compact
+      { delivery: Delivery.from(id, messages), messages: messages.select { |m| m.kind == :message } }
+    end
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: peerpressure
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Forrest Chang
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: List live Claude Code and Codex sessions, send them messages, and hear
+  back, from Ruby or the peer CLI. Idle sessions wake up and act. Honest delivery
+  status (held, denied, expired) instead of a fake 'sent'. Local Unix sockets, same
+  user, no network.
+email:
+executables:
+- peer
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/for_llms.md
+- exe/peer
+- lib/peerpressure.rb
+- lib/peerpressure/delivery.rb
+- lib/peerpressure/message.rb
+- lib/peerpressure/peer.rb
+- lib/peerpressure/registration.rb
+- lib/peerpressure/registry.rb
+- lib/peerpressure/sender.rb
+- lib/peerpressure/session.rb
+- lib/peerpressure/version.rb
+homepage: https://github.com/fkchang/peerpressure
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/fkchang/peerpressure
+  changelog_uri: https://github.com/fkchang/peerpressure/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/fkchang/peerpressure/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: 'Message other AI agents on your machine: list and message live Claude Code
+  and Codex sessions'
+test_files: []