gptqueue

Inter-agent message queue over MCP + Redis.

Start here: docs/QUICKSTART.md — install, connect two agents, and land your first acknowledged task in ten minutes. The delivery contract you operate under (at-least-once semantics, idempotency obligations, dead-letter and renewal policy) is specified in docs/OPERATING_RULES.md.

gptqueue lets AI agents (Claude Code, Codex, Gemini CLI, or any MCP-compatible client) discover each other and exchange messages through a shared Redis-backed queue. Each agent registers with a name and description, then sends and receives typed messages via MCP tool calls.

Architecture

                           MCP (stdio)
┌─────────────┐  ◄──────────────────────►  ┌──────────────┐
│  AI Agent A  │                            │              │
└─────────────┘                             │  gptqueue    │
                           MCP (HTTP)       │  MCP server  │◄─────► Redis
┌─────────────┐  ◄──────────────────────►  │              │
│  AI Agent B  │                            │  (sessions)  │
└─────────────┘                             └──────────────┘

Each agent gets its own bounded inbox queue in Redis. Messages are delivered atomically via a Lua script that enforces queue size limits.

Agent identity is backed by Redis session records with TTL-based leases, so sessions survive process restarts and work across transport boundaries.

Related MCP server: agent-mesh

Components

Design Reports

• Autonomous Agent Coordination Product Thesis

• Session and Transport Redesign Report

MCP Tools

Registered shell (additional tools)

The registered shell (bin/gptqueue-session) registers four additive tools on top of the table above:

package.json maps only gptqueue-server, gptqueue-http, and gptqueue-pty as installed commands; the registered-shell and wrapper entry points are repo-local — invoke them as node bin/<entry> (for example node bin/gptqueue-session).

Dead-letter queue (provisional policy)

Lazy recovery (in claims-recover.lua) counts, per message, how many times a delivered-but-unacked task has been re-queued. Once that count exceeds a cap, the task is moved to the actor's dead-letter queue (gptq:dlq:<actor>) instead of the inbox, so a message that repeatedly fails after expiry cannot bounce forever. The competing constants below are provisional policy: they are named, documented placeholders pending principal calibration, and tuning them is policy, not code.

• RECOVER_CAP = 5 — max recoveries of one message before lazy recovery quarantines it to the DLQ.

• DLQ_MAX_LENGTH = 1000 — per-actor DLQ bound; the newest entries are kept and older trimmed entries are dropped (they were already dead-lettered once).

• RECOVER_COUNTER_TTL_SECONDS = 604800 — TTL on each per-message recovery counter, bounding orphans (7 days).

Acknowledging a claim clears the counters of its tasks, and dlq_requeue restores a fresh budget, so a message can be inspected and re-driven indefinitely. Only id-bearing envelopes are counted; a legacy envelope without a stable message id is re-queued without counter accounting.

Claim renewal (provisional budget policy)

renew_claim extends an outstanding claim's expiry so a runtime can keep a long-running batch alive without surrendering it to lazy recovery. The extension is applied from the renew instant but is capped so a claim can never be renewed more than CLAIM_LIFETIME_BUDGET_SECONDS past its original claimed_at. This budget is provisional policy: it is a named, documented placeholder pending principal calibration, and tuning it is policy, not code.

• CLAIM_LIFETIME_BUDGET_SECONDS = 86400 — max lifetime of any claim measured from claimed_at (1 day); renew_claim refuses an extension that would push past it (budget_exceeded) and cannot resurrect an already-expired claim (claim_expired).

Prerequisites

• Node.js >= 20

• Redis running locally (default redis://127.0.0.1:6379)

Install

From npm (ships prebuilt; provides gptqueue-server, gptqueue-http and gptqueue-pty):

npm install -g gptqueue

gptqueue-pty needs the native node-pty module. If your npm holds back dependency install scripts, approve node-pty (npm install-scripts approve node-pty) so it can build.

From source:

git clone https://github.com/rahulrajaram/gptqueue.git
cd gptqueue
npm install   # builds automatically via prepare

Transports

Stdio (direct, single-client)

For local use with one MCP client:

node /path/to/gptqueue/dist/mcp-server/index.js [agent-name]

Or set GPTQ_AGENT_NAME in the environment.

HTTP (shared, multi-client)

For shared hosting without bridges like supergateway:

node /path/to/gptqueue/dist/transports/http.js --port 3001

Each connecting client gets its own MCP session backed by Redis. Sessions survive reconnects.

Security boundary

The HTTP server binds loopback (127.0.0.1) by default. For the local single-host deployment the security boundary is this loopback bind: only processes on the same machine can reach the MCP endpoint, so no token is required by default.

Two environment variables control the surface:

Refusal rule: if GPTQUEUE_HOST is set to a non-loopback address and GPTQUEUE_HTTP_TOKEN is unset or empty, the server refuses to start (exit non-zero before listening, with a clear message) rather than expose an unauthenticated MCP surface to every reachable host. If the host is loopback (127.0.0.1 / localhost), the token is optional and the local default remains loopback + tokenless. The startup log states the bind host and whether token auth is active (it never prints the token value).

Example — token-authenticated server reachable from other machines:

GPTQUEUE_HOST=0.0.0.0 \
GPTQUEUE_HTTP_TOKEN=$(openssl rand -hex 32) \
  nohup node /path/to/gptqueue/dist/transports/http.js --port 3001 > /tmp/gptqueue.log 2>&1 &

GPTQueue is an external/shared coordination plane; use it in place of native in-session agent collaboration for a workflow, not concurrently with it.

Tool responses retain their legacy text JSON and also expose normalized structuredContent. Failures use stable codes such as REDIS_UNAVAILABLE, SESSION_UNAVAILABLE, AGENT_NOT_REGISTERED, and QUEUE_FULL.

Health check: GET /health returns {"status":"ok","sessions":N}.

Wake launch allowlist (PROVISIONAL)

When a durable wake_if_offline actor is woken, the server spawns the actor's registered launch_command directly (shell:false, never interpolated into a string). Historically that command was copied verbatim, which let a caller register an arbitrary program (or a shell like /bin/sh -c <payload>) and trigger it via send_message → wake. To close that hole, GPTQueue now gates every runtime launch behind an operator allowlist.

The allowlist is an operator-authored file at $XDG_CONFIG_HOME/gptqueue/launch-allowlist.json (default ~/.config/gptqueue/launch-allowlist.json), deliberately outside any agent workspace: an allowlist that agents can edit is one they can authorize themselves with. Override the path with GPTQUEUE_LAUNCH_ALLOWLIST, and keep it somewhere agents cannot write. Symlinks and group- or world-writable files are refused. A legacy ./.gptqueue/launch-allowlist.json in the working directory is no longer read; the refusal message names the new location. Format (version 2):

{
  "version": 2,
  "commands": [
    {
      "command": "/absolute/path/or/name",
      "allowed_args": [["--agent", "alice"], []],
      "comment": "optional human note"
    }
  ]
}

Matching rules (identical at admission and at dispatch):

• A requested launch_command must satisfy an allowlisted entry's identity exactly — never by basename aliasing. A bare-name entry matches only the byte-identical bare name; an absolute-path entry matches only an absolute request that path.resolves to the same path. /attacker/work/node does NOT match an allowlisted node.

• A requested arg vector must equal one allowed_args template exactly: same length, every element identical. There is no suffix freedom, and [] accepts only a request with no args.

• launch_cwd, when provided, must be an existing directory within the server workspace root (path.resolve + prefix check; realpath-based symlink-escape handling is intentionally out of scope).

Fail-closed semantics:

• A new wake_if_offline registration is refused with a typed error (launch_not_allowlisted) if the allowlist file is absent, unparseable, or does not permit the requested command/args. Already-admitted actors keep functioning.

• Dangerous delegators — a command whose basename is a shell (sh, bash, zsh, dash, fish, ksh, cmd, powershell, pwsh) or a shell carrying -c/-lc/-Command — are rejected regardless of the allowlist (launch_command_rejected).

• Interpreter inline-code flags are rejected regardless of the allowlist (launch_command_rejected): a command whose basename is an interpreter (node, deno, bun, tsx, ts-node, python, python2, python3, ruby, perl, php, awk) carrying -e/--eval/-c/--command is an arbitrary-code channel even under an exact-template grant. Point the interpreter at a fixed script file instead (node /path/to/runtime.mjs).

• Version-1 documents (basename matching + unbounded allowed_args_prefixes suffixes) are rejected at parse time with a migration message; they cannot be soundly auto-converted to exact templates.

• Rejections apply again at dispatch (dispatchLaunch re-reads the allowlist), so a stale actor-directory entry cannot spawn a command the operator has since disallowed. A refused dispatch surfaces as wake.status: "launch_failed" on the send.

PROVISIONAL: the global operator allowlist is a stop-gap. It is slated to be replaced by per-actor operator grants (each actor may only launch programs its own operator explicitly granted). Operators should treat the allowlist as the minimum permit set and audit it regularly.

Configuration

Claude Code (stdio)

Add to ~/.claude.json under mcpServers:

{
  "gptqueue": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/gptqueue/dist/mcp-server/index.js"]
  }
}

Claude Code (HTTP)

Start the HTTP server, then configure the client to connect:

# Start the server
node /path/to/gptqueue/dist/transports/http.js --port 3001

{
  "gptqueue": {
    "type": "streamable-http",
    "url": "http://127.0.0.1:3001/mcp"
  }
}

Hook script

Optionally add the hook script to ~/.claude/settings.json for automatic startup context and exit gating:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "/path/to/gptqueue/scripts/check-queue.sh --startup"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "/path/to/gptqueue/scripts/check-queue.sh --stop"
      }]
    }]
  }
}

Environment variables

PTY wrapper

The PTY wrapper lets you run any CLI (e.g. claude, codex) inside a PTY that monitors Redis for incoming messages and injects prompts when the process goes idle:

node bin/gptqueue-pty --agent alice --cmd claude

When a woken agent has pending messages, the injected prompt instructs it to consume via claim_tasks (optional max_batch, ttl_seconds) and confirm with acknowledge_tasks (claim_id) rather than receive_message, so a durable actor woken through the PTY consumes its batch at-least-once.

How it works

1. Registration -- An agent calls register_agent with a name, role, and description. This creates a Redis-backed session with a TTL lease and returns a session_id.

2. Sessions -- Each registration creates a session record in Redis. Sessions have TTL-based leases that are automatically refreshed. An agent can have multiple concurrent sessions (e.g. from different transports).

3. Discovery -- Any agent (even unregistered) can call list_agents to see all registered agents and whether they're online. Online status is computed from active session leases.

4. Messaging -- send_message pushes to the target agent's Redis list (gptq:q:<name>). A Lua script enforces the queue bound atomically. If the queue is full, the sender retries with exponential backoff (up to 10 attempts).

   Resolve-then-push. Before any queue write, send_message resolves the recipient: it proceeds when the target has a durable actor-directory record or is a registered agent; otherwise it rejects the send with a structured unknown_recipient error and creates no queue (gptq:q:<name>) or metadata (gptq:meta:<name>) keys. A typo'd or unknown name can never silently create an orphan mailbox. Self-send (to the caller's own registered name) remains valid.

   Wake-on-send. When the recipient is a durable wake_if_offline actor (see actor_register) with no live runtime and a runnable launch contract, send_message persists the message first, then attempts to wake the actor: it acquires a bounded (60s) per-actor wake lease, and if it owns the lease, spawns the actor's launch command (detached, no shell). The send always succeeds regardless of the wake outcome, and the additive result field wake reports wake_dispatched/wake_coalesced/launch_failed/wake_error. store_only actors and plain agents (no durable record) never wake, so their send behavior is unchanged.

   Pid-liveness reconciliation. When a wake lease records a spawned_pid and the launched runtime never registers (no live session), the actor would otherwise stay pinned in starting until the lease TTL lapses. Presence assembly (both actor_status and send_message's wake gate) reconciles this observationally: if the lease's spawned process is no longer alive, the lease is cleared as a failed activation, so the actor returns to offline and re-wake becomes possible. A live or un-probed (no pid) lease is retained and reported as starting; actor_status's wake_lease payload includes an additive pid_liveness of alive/dead/unknown.

5. Receiving -- receive_message does a blocking pop (BLPOP) with a configurable timeout. For plain agents (no durable actor-directory record) this is unchanged. A durable actor (one with an actor-directory record) is refused with a durable_actor_claim_required error and must consume at-least-once via claim_tasks (returns a claim_id) then acknowledge_tasks (claim_id) instead, so the legacy destructive pop never silently drops a durable actor's message.

6. Session close -- close_session drops the live session but preserves the mailbox. Queued messages remain available for a future session.

7. Unregister -- unregister_agent closes the session AND deletes the mailbox. This is a destructive operation.

Known Limitations

Bridge-based transport (supergateway)

When using the stdio transport behind a bridge like supergateway, tool calls may land in different worker processes. The recommended solution is to use the native HTTP transport instead, which eliminates the need for bridges entirely.

If you must use a stateless or bridge-based transport, capture the session_id returned by register_agent and pass it to session-scoped tools such as send_message, receive_message, close_session, and unregister_agent.

Child-process accumulation

If still using bridges, they can accumulate orphaned gptqueue worker processes. To check and clean up:

# Count gptqueue child workers
pgrep -f 'gptqueue' | wc -l

# Review candidates first: -f matches any command line containing the text,
# including servers from other checkouts
pgrep -af 'dist/mcp-server/index.js'
# then stop only the PIDs you have confirmed are orphaned
kill <pid> ...

Stdio servers now exit on their own when their client closes stdin, so orphans should only come from older builds.

License

MIT