gptqueue

CI

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

MCP Tools

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

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).

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

3. 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).

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

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

License

MIT