Skip to content

feat: replace TCP loopback with Unix Domain Socket for CLI→Proxy IPC #184

@kianwoon

Description

@kianwoon

Problem

Claude Code CLI and ModelWeaver proxy run on the same machine, but communicate via TCP (127.0.0.1:3456). Every request pays full TCP/IP stack overhead — handshake, Nagle, checksums — all unnecessary for local IPC.

Proposal

Replace TCP listen with Unix Domain Socket (/tmp/modelweaver.sock or similar).

Expected Benefits

  • ~30-50% lower per-request latency (kernel memory copy vs TCP stack)
  • No SYN/ACK, no checksums, no Nagle's algorithm
  • Naturally supports SCM_RIGHTS for future zero-copy optimizations

Implementation Notes

  • @hono/node-server uses Node's http.createServer() — need to switch to http.createServer(app) + .listen(socketPath) or use Node net module directly
  • Must preserve TCP fallback for remote GUI access (Tauri app connects from localhost)
  • Consider dual-listen: UDS for CLI, TCP for GUI/metrics
  • Update daemon.ts PID/port discovery to handle UDS paths
  • Update monitor.ts health checks for UDS

Configuration

server:
  socket: /tmp/modelweaver.sock  # new: UDS path (overrides port if set)
  port: 3456                      # kept for GUI/metrics access

Acceptance Criteria

  • Proxy listens on UDS when server.socket is configured
  • TCP port still works for GUI/metrics endpoints
  • ANTHROPIC_BASE_URL or equivalent can point to UDS
  • CLI→Proxy latency measurable improvement vs TCP

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions