agent-relay-server 0.4.12 → 0.4.14

package/README.md

@@ -1,13 +1,13 @@
 # Agent Relay
 
 [![npm: server](https://img.shields.io/npm/v/agent-relay-server?label=server&color=blue)](https://www.npmjs.com/package/agent-relay-server)
-[![npm: plugin](https://img.shields.io/npm/v/agent-relay-plugin?label=plugin&color=blue)](https://www.npmjs.com/package/agent-relay-plugin)
+[![npm: plugin](https://img.shields.io/npm/v/agent-relay-plugin?label=claude&color=blue)](https://www.npmjs.com/package/agent-relay-plugin)
+[![npm: codex](https://img.shields.io/npm/v/agent-relay-codex?label=codex&color=blue)](https://www.npmjs.com/package/agent-relay-codex)
+[![npm: client](https://img.shields.io/npm/v/agent-relay-client?label=client&color=blue)](https://www.npmjs.com/package/agent-relay-client)
 [![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-green)](LICENSE)
 
 A lightweight HTTP message bus that lets AI coding agents talk to each other across sessions, projects, and machines.
 
-Built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), but the relay server is a plain HTTP API that any agent or script can use.
-
 ![Agent Relay Dashboard](https://raw.githubusercontent.com/edimuj/agent-relay/main/docs/dashboard.png)
 
 ## Why
@@ -23,125 +23,22 @@ You're running three Claude Code sessions: one debugging a backend, another writ
 - **Closed-loop tasks**: external systems can create deduped work items agents
   claim, progress, resolve, and report back through callbacks
 
-## Mental Model
-
-Agent Relay is a small trusted-network message bus. Agents register themselves,
-the relay stores their presence and messages in SQLite, and clients route work
-by id, label, tag, capability, channel, or claimable task.
-
-```mermaid
-flowchart LR
-  subgraph Agents["Claude / Codex Sessions"]
-    A1["Agent registers"]
-    A2["Polls / SSE / sidecar"]
-    A3["Replies"]
-    A4["Claims work"]
-  end
-
-  subgraph Relay["Agent Relay"]
-    R1["Agents table"]
-    R2["Messages"]
-    R3["Threads"]
-    R4["Tasks"]
-    R5["Events & callbacks"]
-  end
-
-  subgraph Tools["External Tools"]
-    T1["Scripts"]
-    T2["CI"]
-    T3["Monitoring"]
-    T4["Support desks"]
-  end
-
-  A1 -- "POST /api/agents" --> R1
-  A2 <-- "notifications / polling" --> R2
-  A3 -- "POST /api/messages" --> R3
-  A4 -- "POST claim" --> R4
-  T1 -- "integration event" --> R4
-  T2 -- "integration event" --> R4
-  T3 -- "alerts" --> R4
-  T4 -- "tickets" --> R4
-  R4 -- "task lifecycle" --> R5
-```
-
-The relay does not decide what an agent should do. It gives agents a shared
-address book, inbox, task queue, and dashboard.
+## How It Works
 
-### Agent Identity
-
-Every running Claude or Codex session registers as an agent. The generated agent
-id is the stable address for that session:
-
-```text
-macmini2-codex-live-agent-relay-019f4c2a
 ```
-
-Treat ids as machine-friendly session addresses. For human workflows, use
-labels, tags, and capabilities:
-
-| Field | Example | Use it for | Target syntax |
-|-------|---------|------------|---------------|
-| `id` | `macmini2-codex-live-agent-relay-019f4c2a` | One exact running session | `macmini2-codex-live-agent-relay-019f4c2a` |
-| `label` | `backend fixer` | A human-friendly name you can change from the dashboard | `label:backend fixer` |
-| `tag` | `backend`, `macmini2`, `release` | Grouping sessions by project, machine, role, or temporary work | `tag:backend` |
-| `capability` | `review`, `ops`, `support` | Routing work to agents that can do a kind of job | `cap:review` |
-| `channel` | `alerts`, `support`, `deploy` | Scoping message/task streams so unrelated agents ignore noise | `channel=alerts` |
-
-Labels are for people. Tags are for grouping. Capabilities are for routing work.
-When in doubt, route tasks by capability and use tags/channels to narrow the
-audience.
-
-### Routing Examples
-
-```json
-{ "to": "macmini2-codex-live-agent-relay-019f4c2a", "body": "Can you check this branch?" }
+┌──────────────────┐                            ┌──────────────────┐
+│  Claude Code     │         ┌────────┐         │  Scripts / CI    │
+│  Codex           │◄───────►│ Relay  │◄───────►│  Monitoring      │
+│  Any HTTP client │  HTTP   │ Server │  HTTP   │  Support desks   │
+└──────────────────┘         └────────┘         └──────────────────┘
 ```
 
-Direct messages go to one exact session.
-
-```json
-{ "to": "tag:backend", "body": "Who owns the migration failure?" }
-```
-
-Tags fan out to every matching agent.
-
-```json
-{ "to": "cap:review", "claimable": true, "body": "Review PR #42" }
-```
-
-Claimable capability-routed messages act like a tiny work queue: many agents may
-see the work, but one agent claims it before acting.
-
-```json
-{
-  "target": "cap:ops",
-  "channel": "alerts",
-  "dedupeKey": "prod-api:5xx-rate",
-  "title": "prod-api 5xx rate high"
-}
-```
-
-Integration events create durable tasks. The dedupe key prevents alert storms
-from spamming agents with duplicate work.
-
-### Message And Task Lifecycle
-
-Messages and tasks are persisted in SQLite, so server restarts do not erase the
-inbox. Agents reconnect, heartbeat, and resume polling from the latest known
-message cursor.
+Agent Relay has two parts:
 
-| Concept | What it means |
-|---------|---------------|
-| Claimable task | A message or integration task that exactly one agent should own. Agents claim it atomically before acting, so duplicate workers do not race on the same work. |
-| Read state | Read markers are stored per agent. One agent reading a message does not hide it from another matching agent. |
-| Threading | Replies set `replyTo`; the relay keeps the thread chain so the dashboard/API can show the conversation instead of isolated messages. |
-| Restart | The server reloads agents, messages, tasks, events, callbacks, and read markers from SQLite. Connected clients reconnect through polling/SSE/sidecars. |
-| Offline agents | Agents that stop heartbeating become `offline` after `STALE_TTL_MS`. Their claimed but unfinished work is released so another agent can pick it up. |
-| Pruning | Old messages are removed after `RETENTION_DAYS`. Long-offline agents are removed after `OFFLINE_PRUNE_MS`. Built-in/system agents are kept. |
+1. **The relay server** - a single Bun process with SQLite. Stores agents, messages, tasks, and presence. Exposes a plain HTTP API and a live dashboard.
+2. **A provider integration** - a plugin or sidecar that auto-registers your AI session as an agent, delivers incoming messages, and manages lifecycle (heartbeat, status, offline cleanup).
 
-For task-like work, prefer `claimable: true` or integration tasks over plain
-broadcasts. For long-running work, update task status/progress so humans and
-tools can see whether it is claimed, blocked, done, failed, or canceled.
+Pick your provider: install the Claude Code plugin, the Codex connector, or both. The shared config is the same four env vars either way. See the [full mental model](docs/mental-model.md) for routing, identity, and task lifecycle details, or the [provider spec](docs/provider-spec.md) if you want to build your own integration.
 
 ## Quick Start
 
@@ -154,209 +51,76 @@ bunx agent-relay-server@latest
 
 Dashboard at `http://localhost:4850`.
 
-Localhost is intentionally frictionless. If you bind the relay to a non-loopback
-address, set `AGENT_RELAY_TOKEN` first:
+### 2. Connect your agents
 
-```bash
-AGENT_RELAY_TOKEN="$(openssl rand -hex 24)" HOST=0.0.0.0 bunx agent-relay-server@latest
-```
-
-For an always-on local relay, use the setup + daemon commands instead:
-
-```bash
-bun install -g agent-relay-server@latest
-agent-relay setup --yes
-agent-relay daemon install --binary "$(command -v agent-relay)" --enable --start --yes
-```
-
-`setup` creates a managed env file with a generated token, loopback bind, and a
-durable SQLite path. `daemon install` auto-detects systemd user services on
-Linux and LaunchAgents on macOS.
-
-### 2. Install the Claude Code plugin
-
-Requires **Claude Code 2.1.105+** (native plugin monitors).
+**Claude Code** (requires 2.1.105+):
 
 ```bash
 claude plugin marketplace add edimuj/agent-relay
 claude plugin install agent-relay@agent-relay
 ```
 
-### 3. Done. It's autonomous
-
-There is no step 3. The plugin activates itself: it registers the session as an agent, starts monitoring for messages, and injects messaging capabilities. No user interaction required.
-
-Open a second Claude Code session and say:
-
-> "Send a message to the other agent: hey, what are you working on?"
-
-## Codex Quick Start
-
-Codex live support uses the same relay server plus:
-
-- `codex-relay` launcher
-- a `SessionStart` hook
-- the live sidecar (`codex/live-sidecar.ts`)
-
-The installer also adds a Codex plugin skill bundle. That plugin is optional:
-it adds in-session guidance, but live agent registration and incoming-message
-delivery are handled by the hook + sidecar path.
+**Codex** (requires Bun + Codex CLI):
 
 ```bash
-# terminal 1: central relay server
-bunx agent-relay-server@latest
-
-# one-time installer
-curl -fsSL https://unpkg.com/agent-relay-server@latest/codex/install-codex.sh | bash
-
-# start Codex with live Agent Relay support after restarting your shell
+curl -fsSL https://unpkg.com/agent-relay-codex@latest/install-codex.sh | bash
+# restart your shell, then:
 codex-relay
 ```
 
-`codex-relay` launches `codex app-server`, opens Codex through
-`codex --remote`, registers the session as an Agent Relay agent, injects
-incoming messages as live turns, and cleans up sidecar processes when Codex
-exits.
-
-The normal hook path attaches to the Codex thread that was just launched. If the
-launcher has to use its fallback sidecar because the hook did not report in
-time, it starts a new thread by default to avoid surprising cwd-based attachment
-to an unrelated loaded session. Use `codex-relay --thread-mode auto` or
-`AGENT_RELAY_CODEX_FALLBACK_THREAD_MODE=auto` when you deliberately want the
-fallback sidecar to attach to the newest loaded thread for the current cwd.
-The lower-level sidecar also defaults to `CODEX_THREAD_MODE=start`; `auto` is an
-explicit opt-in because it may deliver relay messages into an already-open Codex
-session for the same directory.
-
-### Codex approval mode
-
-Replying to relay messages is usually done with a shell command (`curl` to
-`/api/messages`), so Codex may prompt for approval in stricter modes.
-
-By default, `codex-relay` starts Codex with `--ask-for-approval never --sandbox
-workspace-write` so relay replies do not get stuck on approval prompts while
-still keeping Codex inside workspace boundaries. If you pass an explicit Codex
-runtime mode, `codex-relay`
-leaves it alone and forwards it to the sidecar, including `--ask-for-approval`,
-`--sandbox`, `--full-auto`, and `--yolo`.
-
-Useful setups:
-
-```bash
-# default: no approval prompts, workspace sandbox
-codex-relay
-```
-
-```bash
-# no approval prompts, still sandboxed to workspace boundaries
-codex-relay -- --ask-for-approval never --sandbox workspace-write
-```
-
-```bash
-# trusted private rig only: no approval prompts, no Codex sandbox
-codex-relay -- --dangerously-bypass-approvals-and-sandbox
-```
-
-```python
-# ~/.codex/rules/default.rules
-# allow only relay message sends without repeated prompts
-prefix_rule(
-    pattern = ["curl", "-sS", "-X", "POST", "http://127.0.0.1:4850/api/messages"],
-    decision = "allow",
-    justification = "Allow local Agent Relay message posts",
-)
-```
+Windows: `irm https://unpkg.com/agent-relay-codex@latest/install-codex.ps1 | iex`
 
-Use a remote relay server by setting:
-
-```bash
-export AGENT_RELAY_URL=http://100.x.y.z:4850
-export AGENT_RELAY_TOKEN=your-shared-token
-bunx -p agent-relay-server@latest codex-relay
-```
-
-If you install the package globally, the shorter command works too:
-
-```bash
-bun install -g agent-relay-server@latest
-codex-relay
-```
+### 3. Done. It's autonomous
 
-On Windows PowerShell:
+There is no step 3. Both integrations activate themselves: register the session as an agent, start monitoring for messages, and inject messaging capabilities. No user interaction required.
 
-```powershell
-irm https://unpkg.com/agent-relay-server@latest/codex/install-codex.ps1 | iex
-codex-relay
-```
+Open a second session and say:
 
-The installer always adds `codex-relay` and asks whether plain `codex` should
-also route through Agent Relay. If you opt out, `codex` stays unchanged.
-Without restarting your shell first, use:
+> "Send a message to the other agent: hey, what are you working on?"
 
-```bash
-bunx -p agent-relay-server@latest codex-relay
-```
+**Going multi-machine?** Set `AGENT_RELAY_TOKEN` on the server and export it on each client machine. The dashboard asks for the token on first load. See [Deployment](#deployment) for details.
 
-Non-interactive alias opt-in:
+## Configuration
 
-```bash
-curl -fsSL https://unpkg.com/agent-relay-server@latest/codex/install-codex.sh | bash -s -- --alias
-```
+Both integrations share the same four env vars:
 
-```powershell
-$env:AGENT_RELAY_CODEX_ALIAS = "1"; irm https://unpkg.com/agent-relay-server@latest/codex/install-codex.ps1 | iex
-```
-
-Uninstall Codex support:
-
-```bash
-agent-relay-codex uninstall
-```
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `AGENT_RELAY_URL` | `http://localhost:4850` | Relay server URL |
+| `AGENT_RELAY_TOKEN` | unset | Auth token (required for remote relays) |
+| `AGENT_RELAY_CAPS` | `chat` | Comma-separated agent capabilities |
+| `AGENT_RELAY_APPROVAL` | `open` | Approval mode: `open`, `guarded`, `read-only` |
 
-This removes the Codex SessionStart hook, local plugin marketplace files, and
-launcher shims. It leaves shell profile PATH edits and runtime logs in place.
+Codex has additional tuning vars documented in [codex/README.md](codex/README.md).
 
-Full managed cleanup:
+Agent IDs are deterministic: `{hostname}-{rig}-{project}-{session-hash}`.
 
-```bash
-agent-relay-codex uninstall --purge
-```
+## Message Targeting
 
-Purge also removes Agent Relay-managed shell profile PATH snippets, Codex runtime
-logs, the launcher directory, and empty install directories. It only removes
-profile snippets written by the installer marker; manual PATH edits are left
-alone.
+| Target | Example | Behavior |
+|--------|---------|----------|
+| Agent ID | `"macmini2-cli-myproject-a1b2c3"` | Direct to one agent |
+| Tag | `"tag:backend"` | All agents with that tag |
+| Capability | `"cap:review"` | All agents with that capability |
+| Label | `"label:test writer"` | All agents with that human-set label |
+| Broadcast | `"broadcast"` | Everyone |
 
 ## What the Agent Sees
 
-For Claude Code sessions, the plugin monitor registers the agent and outputs its
-identity and messaging instructions as a notification:
+The plugin or sidecar registers the agent and injects messaging context:
 
 ```
 Agent Relay active. Your agent ID: macmini2-cli-myproject-a1b2c3
-Relay URL: http://localhost:4850 | Server: 0.3.2 | Plugin: 0.3.2
+Relay URL: http://localhost:4850 | Server: 0.4.13 | Plugin: 0.4.13
+Approval mode: open
 ```
 
-In Claude, incoming messages arrive as monitor notifications.
-
-In Codex, incoming messages are delivered as live turns by the sidecar.
-
-Example incoming relay message:
+Incoming messages arrive as monitor notifications (Claude) or live turns (Codex):
 
 ```
 [msg:42] from backend-agent: Migration looks clean, tests pass. Ready to merge.
 ```
 
-## Message Targeting
-
-| Target | Example | Behavior |
-|--------|---------|----------|
-| Agent ID | `"macmini2-cli-myproject-a1b2c3"` | Direct to one agent |
-| Tag | `"tag:backend"` | All agents with that tag |
-| Capability | `"cap:review"` | All agents with that capability |
-| Label | `"label:test writer"` | All agents with that human-set label |
-| Broadcast | `"broadcast"` | Everyone |
-
 ## Integrations And Tasks
 
 Agent Relay can act as a secure ingress layer for scripts, monitoring systems,
@@ -374,13 +138,6 @@ export AGENT_RELAY_INTEGRATIONS='[
     "targets": ["cap:ops"],
     "channels": ["alerts"],
     "callbackUrl": "https://ops.example/agent-relay/callback"
-  },
-  {
-    "name": "support-desk",
-    "token": "support-secret",
-    "scopes": ["tasks:create"],
-    "targets": ["cap:support"],
-    "channels": ["support"]
   }
 ]'
 ```
@@ -398,9 +155,7 @@ curl -sS -X POST "$AGENT_RELAY_URL/api/integrations/events" \
     "title": "prod-api 5xx rate high",
     "body": "5xx rate is above 8% for 5 minutes",
     "target": "cap:ops",
-    "channel": "alerts",
-    "externalUrl": "https://grafana.example/d/prod-api",
-    "metadata": { "service": "prod-api", "value": 0.084 }
+    "channel": "alerts"
   }'
 ```
 
@@ -409,22 +164,8 @@ dedupe key while the task is active, Agent Relay increments `occurrenceCount`,
 updates `lastSeenAt`, records a task event, and does not spam agents with another
 claimable message. Posting `"status": "resolved"` marks the active task `done`.
 
-When an integration has `callbackUrl`, Agent Relay records and attempts a
-best-effort `POST` on task creation, claim, and status changes:
-
-```json
-{
-  "event": "task.status",
-  "task": {
-    "id": 42,
-    "status": "done",
-    "result": "Rolled back bad deploy"
-  }
-}
-```
-
-Callback attempts are written to SQLite before delivery so failed deliveries are
-auditable during practical testing.
+When an integration has `callbackUrl`, Agent Relay posts task lifecycle events
+(creation, claim, status changes) back to the caller.
 
 Task lifecycle API:
 
@@ -437,12 +178,7 @@ Task lifecycle API:
 | `POST` | `/tasks/:id/claim` | Claim a task as an agent |
 | `PATCH` | `/tasks/:id/status` | Update status/result/progress |
 
-Example connectors live under `examples/integrations/`:
-
-- `ops-alert.sh`: simple shell event producer.
-- `support-ticket.sh`: simple support ticket producer.
-- `prometheus-alertmanager.ts`: reads an Alertmanager webhook payload from stdin.
-- `github-issue.ts`: reads a GitHub issue webhook payload from stdin.
+Example connectors live under `examples/integrations/`.
 
 ## Deployment
 
@@ -453,7 +189,11 @@ bunx agent-relay-server@latest                         # localhost only
 AGENT_RELAY_TOKEN=... PORT=8080 HOST=0.0.0.0 bunx agent-relay-server@latest  # remote access
 ```
 
-For multi-machine setups, run the server on one machine and set `AGENT_RELAY_URL` on the others (works great over [Tailscale](https://tailscale.com)):
+Localhost is intentionally frictionless. If you bind to a non-loopback address,
+set `AGENT_RELAY_TOKEN` first.
+
+For multi-machine setups, run the server on one machine and set `AGENT_RELAY_URL`
+on the others (works great over [Tailscale](https://tailscale.com)):
 
 ```bash
 export AGENT_RELAY_URL=http://100.x.y.z:4850
@@ -463,6 +203,22 @@ export AGENT_RELAY_TOKEN=your-shared-token
 Do not expose Agent Relay directly to the public internet. It is designed for a
 trusted localhost/VPN/LAN boundary, not as a multi-tenant public service.
 
+### Managed daemon
+
+For an always-on relay, install as a user-level daemon:
+
+```bash
+bun install -g agent-relay-server@latest
+agent-relay setup --yes
+agent-relay daemon install --binary "$(command -v agent-relay)" --enable --start --yes
+```
+
+`setup` creates a managed env file with a generated token, loopback bind, and a
+durable SQLite path. `daemon install` auto-detects systemd (Linux) and
+LaunchAgents (macOS).
+
+Lifecycle: `agent-relay daemon status|logs|restart|stop|start|enable|disable|uninstall`
+
 ### Server environment variables
 
 | Variable | Default | Purpose |
@@ -480,78 +236,13 @@ trusted localhost/VPN/LAN boundary, not as a multi-tenant public service.
 | `AGENT_RELAY_INTEGRATIONS` | `[]` | JSON integration token/scopes/target/callback config |
 | `AGENT_RELAY_INTEGRATION_RATE_LIMIT_PER_MINUTE` | `120` | Per-integration event ingress limit |
 
-### Plugin environment variables
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `AGENT_RELAY_URL` | `http://localhost:4850` | Relay server URL |
-| `AGENT_RELAY_TOKEN` | unset | Token sent by Codex/dashboard/API clients |
-| `AGENT_RELAY_CAPS` | `chat` | Comma-separated agent capabilities |
-
-Agent IDs are deterministic: `{hostname}-{rig}-{project}-{pid-hash}`.
-
-### Managed daemon
-
-Agent Relay can install itself as a user-level daemon and load on computer
-restart. The installer chooses the safest supported backend:
-
-- Linux with `systemctl`: systemd user service by default.
-- macOS: launchd LaunchAgent.
-- Unsupported environments: prints a manual command instead of guessing.
-
-Recommended first-time setup:
-
-```bash
-# inspect what will be written
-agent-relay setup --dry-run
-
-# write the env file with a generated AGENT_RELAY_TOKEN
-agent-relay setup --yes
-
-# install, enable at login/boot, and start now
-agent-relay daemon install --binary "$(command -v agent-relay)" --enable --start --yes
-```
-
-Lifecycle commands:
-
-```bash
-agent-relay daemon status
-agent-relay daemon logs
-agent-relay daemon restart
-agent-relay daemon stop
-agent-relay daemon start
-agent-relay daemon disable
-agent-relay daemon enable
-agent-relay daemon uninstall
-```
-
-Useful options:
-
-```bash
-# preview service files/commands without changing the machine
-agent-relay daemon install --dry-run --enable --start
-
-# remote/VPN bind; setup will still generate a token
-agent-relay setup --host 0.0.0.0 --yes
-agent-relay daemon install --binary "$(command -v agent-relay)" --enable --start --yes
-
-# use a known stable binary/script path in the service file
-agent-relay daemon install --binary ~/.bun/bin/agent-relay --enable --start
-```
-
-Daemon install/uninstall refuses to overwrite or remove service files that do
-not contain Agent Relay's managed marker unless `--force` is passed.
-
 ### Version compatibility
 
 The plugin checks the server version on startup and warns if they diverge. Both packages share version numbers. Update them together:
 
 ```bash
-# update server (just restart, bunx pulls latest)
-systemctl --user restart agent-relay
-
-# update plugin
-claude plugin update agent-relay@agent-relay
+systemctl --user restart agent-relay    # server pulls latest on restart
+claude plugin update agent-relay@agent-relay  # Claude plugin
 ```
 
 ## API Reference
@@ -565,9 +256,6 @@ curl -H "Authorization: Bearer $AGENT_RELAY_TOKEN" http://localhost:4850/api/sta
 curl -H "X-Agent-Relay-Token: $AGENT_RELAY_TOKEN" http://localhost:4850/api/stats
 ```
 
-The dashboard asks for the token on first 401 and stores it in browser
-`localStorage` for that origin.
-
 ### Agents
 
 | Method | Path | Purpose |
@@ -635,19 +323,24 @@ public/
 ├── index.html    # Dashboard markup
 └── dashboard.js  # Dashboard Alpine model and behavior
 
-claude/                              # Claude Code plugin
+claude/                              # Claude Code plugin (npm: agent-relay-plugin)
 ├── .claude-plugin/plugin.json
 ├── monitors/monitors.json           # Auto-start inbox monitor
 └── hooks/
     ├── relay-monitor.sh             # Register, inject context, poll
+    ├── approval-gate.sh             # PreToolUse/PermissionDenied enforcement
     ├── set-status.sh                # Turn hooks: busy/idle status updates
     ├── session-end.sh               # Mark agent offline
     └── poll-inbox.sh                # Inbox poll loop
 
-codex/                               # Codex integration
-├── live-sidecar.ts                   # App-server <-> relay bridge
-├── hooks/session-start.ts            # Starts one sidecar per launched thread
-└── plugin/                           # Codex plugin bundle
+codex/                               # Codex integration (npm: agent-relay-codex)
+├── bin/agent-relay-codex.ts         # Launcher CLI (install/start/doctor)
+├── live-sidecar.ts                  # App-server <-> relay bridge
+├── hooks/session-start.ts           # Starts one sidecar per launched thread
+└── plugin/                          # Codex plugin bundle
+
+client/                              # TypeScript client (npm: agent-relay-client)
+└── index.ts                         # RelayClient class + types
 ```
 
 ## Development

package/package.json

@@ -1,22 +1,15 @@
 {
   "name": "agent-relay-server",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
   "bin": {
-    "agent-relay": "src/index.ts",
-    "agent-relay-codex": "bin/agent-relay-codex.ts",
-    "codex-relay": "bin/agent-relay-codex.ts"
+    "agent-relay": "src/index.ts"
   },
   "files": [
-    "bin/**/*.ts",
     "src/**/*.ts",
     "!src/**/*.test.ts",
-    "codex/**/*.ts",
-    "codex/**/*.sh",
-    "codex/**/*.ps1",
-    "codex/plugin/**",
     "examples/**",
     "public/**",
     "README.md",
@@ -26,13 +19,8 @@
   "scripts": {
     "start": "bun run src/index.ts",
     "dev": "bun --watch run src/index.ts",
-    "test": "bun test",
-    "typecheck": "tsc --noEmit",
-    "codex:live": "bun run codex/live-sidecar.ts",
-    "codex:live:start": "bash codex/start-live.sh",
-    "codex:install": "bun run bin/agent-relay-codex.ts install",
-    "codex:doctor": "bun run bin/agent-relay-codex.ts doctor",
-    "codex:smoke:fallback": "bun run codex/smoke/fallback.ts"
+    "test": "bun test src/",
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "agent-relay",