Gptqueue

gptqueue

[](https://github.com/rahulrajaram/gptqueue/actions/workflows/ci.yml)

Inter-agent message queue over MCP + Redis.

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 server  │◄─────►│ Redis │
┌─────────────┐       MCP (stdio)       │              │       └───────┘
│  AI Agent B  │◄──────────────────────►│              │
└─────────────┘                         └──────────────┘

Each agent gets its own bounded inbox queue in Redis. Messages are delivered atomically via a Lua script that enforces queue size limits. Agents publish heartbeats so others can see who is online.

Components

| Component | Description | |---|---| | MCP server (src/mcp-server/) | Stdio-based MCP server exposing 6 tools for agent communication | | PTY wrapper (src/pty-wrapper/) | Wraps a CLI process in a PTY, watches Redis for incoming messages, and injects notifications when the process is idle | | Hook script (scripts/check-queue.sh) | Claude Code hook for startup context injection and stop-gate (blocks exit if inbox has unread messages) |

MCP Tools

| Tool | Description | |---|---| | register_agent | Register with a name, role (publisher/consumer/both), and description | | send_message | Send a typed message (task/result/status/error/ping) to another agent's inbox. Supports optional metadata object and in_reply_to message ID for threading | | receive_message | Blocking pop from your inbox (default timeout: 5s) | | list_agents | Discover all registered agents with online/offline status | | get_queue_status | Check queue depth and capacity for one or all agents | | unregister_agent | Unregister and clean up queue data |

Prerequisites

• Node.js >= 18
• Redis running locally (default redis://127.0.0.1:6379)

Install

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

Configuration

Claude Code

Add to ~/.claude.json under mcpServers:

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

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"
      }]
    }]
  }
}

Any MCP client

The server speaks stdio MCP. Point your client at:

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

Or set GPTQ_AGENT_NAME in the environment.

Environment variables

| Variable | Default | Description | |---|---|---| | REDIS_URL | redis://127.0.0.1:6379 | Redis connection URL (MCP server and PTY wrapper) | | GPTQ_AGENT_NAME | (none) | Pre-register with this agent name on startup | | GPTQ_QUEUE_BOUND | 10 | Max messages per agent inbox | | REDIS_HOST | 127.0.0.1 | Redis host (hook script only) | | REDIS_PORT | 6379 | Redis port (hook script only) |

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:

gptqueue-pty --agent alice --cmd claude

How it works

1. Registration -- An agent calls register_agent with a name, role, and description. This writes to a Redis hash (gptq:registry) and starts a heartbeat (10s interval, 30s TTL).

1. Discovery -- Any agent (even unregistered) can call list_agents to see all registered agents and whether they're online.

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

1. Receiving -- receive_message does a blocking pop (BLPOP) with a configurable timeout.

1. Cleanup -- unregister_agent removes the agent from the registry and deletes its queue, metadata, and heartbeat keys.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rahulrajaram
• Source: rahulrajaram/gptqueue
• License: MIT

Install and usage instructions live in the source repository linked above.