Claude Gateway

An orchestrator, voice, and multi-channel platform for Claude Code.

Claude Gateway keeps conversations responsive while Claude Code workers execute tasks. Talk or type through your connected channels, follow progress, and carry your agents’ memory and skills across sessions.

Documentation · Quickstart · API reference

Features

• 🔎 Jev evaluations — optional typed Choice, Score and Noul evaluations shared by agents, workers and scoped integrations, with direct or compatible upstream credentials. See Jev setup.

• 🪄 Agent Orchestration Engine — responsive conversations while workers execute durable tasks. The dashboard separates Agent/worker token usage and offers per-session reports with cache and tool details. Existing configurations without the switch are upgraded automatically; explicit false remains an opt-out. See orchestration settings.

• 🔥 Agent orchestration — keep conversations responsive while reusable workers execute durable tasks, report progress, accept follow-up instructions, and support cancellation. See orchestration and tasks.

• ⚙️ Worker harnesses — automatically route GPT workers to native Codex when ready, with Claude Code fallback before dispatch on the host or inside app containers. Conversational agents remain on Claude Code. See worker harnesses.

• 🧰 pstack — load the pstack-claude Claude Code plugin only for agents you set up with /pstack-setup, with per-agent model sheets, subagents as gateway tasks and live review-panel status. See pstack.

• 🎙️ Voice conversations — speech recognition and spoken replies with per-agent models and voices, direct or upstream providers, live or recorded speech input, and audio replay. See voice setup.

• 🧠 Skill self-improvement — agents learn reusable skills from their own work: after a substantive turn a background reviewer creates or updates a skill, hot-reloaded for the next turn. Provenance-guarded (never overwrites human-written skills), capped per day, and audited to SKILLS_LEARNED.md. See gateway.skillLearning

• 📚 Knowledge base (two-lane memory) — per-agent SQLite/FTS5 searchable archive exposed through memory_search / memory_get MCP tools, so agents recall notes that don’t fit the always-injected core; chunks carry fail-closed provenance and the index is refreshed off the gateway event loop. See gateway.knowledge

• 🌙 Nightly dreaming — background consolidation of long-term memory: a print-only reviewer proposes ops that a safe applier writes to MEMORY.md / USER.md (backup, bounded-loss, net-negative when over budget). Deterministic compaction, budget-scaled pruning, and staleness GC keep memory near budget without forgetting — archived entries stay searchable. See gateway.dreaming

• 🤖 Multi-agent — run multiple bots from a single gateway, each with isolated sessions

• 🔒 Isolated memory mode — an agent that serves many unrelated senders keeps USER.md/MEMORY.md per conversation, with the shared memory, skill, cron, agent and app tools turned off; an app agent also runs each conversation in its own sandbox container, and every channel tool replies only to the originating chat. Set agents[].isolateMemory on a host agent or services.agent.isolate_memory in an app’s app.yaml. See isolated memory mode

• 🔌 Multi-channel MCP — modular tool system per channel (Telegram, Discord, LINE, Slack, WhatsApp, Cron, Skills, extensible to more)

• 📥 Channel ingress recovery — unavailable attachments preserve the message and readable files; Telegram/Discord receiver retries isolate conversations and archive stale startup queues without executing old requests. See ingress recovery.

• ⏳ Provider outage admission — durable cooldowns bound repeated report/inference failures, preserve queued input and task results, and expose waiting status without restarting running workers. See provider admission settings.

• 🧩 Agent skills — extensible skill system via SKILL.md files; agents can create, delete, and install skills from URLs at runtime with hot-reload

• 🎭 Agent identity — define personality, tone, and rules via workspace markdown files

• 📡 Live status messages — real-time status updates showing tool usage, thinking, and progress

• ⌨️ Typing indicators — continuous typing animation while the agent is working (Telegram and Discord)

• 🌊 Streaming API — SSE (Server-Sent Events) endpoint for real-time response streaming

• ↪️ Auto-forward — agent text output automatically forwarded to Telegram even without explicit reply tool calls

• ⏰ Heartbeat / scheduled tasks — cron-based proactive messages and recurring tasks via HEARTBEAT.md + REST API; agent jobs deliver output to Telegram, Discord, or both

• 💬 Persistent chat history — two-layer storage: session context (.jsonl) + permanent SQLite DB with FTS5 full-text search; survives /compact and session eviction

• 🧹 Auto-cleanup — configurable retention policy prunes messages and media files older than N days on a daily schedule

• 🗄️ Long-term memory — persistent memory system across sessions

• 🔄 Config auto-migration — automatic schema migration when config format changes

• 🔐 Access control — allowlist, open, or pairing-based Telegram access policies

• 🌐 HTTP API — REST API with key-based auth for external integrations

• 🛍️ App Store — install, update, and host Docker-compose apps on the gateway; apps get a reverse proxy at /app/:name/:portName/*, optional Unix socket bridge for host scripts, and optional AI agent injection

• ⬆️ Self-update — check for newer versions of claude-gateway and claude-code and trigger an update via a single API call (no SSH or shell access needed), or from the terminal with claude-gateway update / claude-gateway claude update; the gateway follows the npm stable dist-tag (--latest for the newest release)

• 💾 Session persistence — conversation history saved and restored across restarts

• 🖥️ PTY shell (wrap-shell mode) — optional interactive pseudo-terminal backend (gateway.headless: false) for tools that require a real TTY; includes a live browser viewer (xterm.js) and a /api/v1/sessions/:sessionId/screen endpoint that returns the visible screen as plain text — agents can poll it to detect hang states, menus, or unexpected output without parsing ANSI escape codes; a /cli chat command (Telegram/Discord/LINE) opens the same viewer for a single agent, agent-scoped and without an admin key; app-agents and orchestration always stay headless

Get started

Install Node.js 22+, Bun, and an authenticated Claude Code CLI with channels support. Orchestration runs on Linux, macOS, and Windows. Docker/Compose is needed for apps; some voice formats require ffmpeg.

npm install -g @0xmaxma/claude-gateway
claude-gateway gateway start

In another terminal:

claude-gateway agents create

Follow the quickstart, then enable orchestration, connect a channel, and optionally configure voice.

Learn more

API documentation lives on the documentation website. CLI command reference is the generated command reference. To edit or preview this site, see website development.

Installation health

Run claude-gateway doctor to check startup, voice and optional Codex dependencies, even when the server is down. Use claude-gateway doctor fix for supported local repairs and installation of missing ffmpeg/ffprobe. Repair asks for confirmation and never starts or restarts the gateway. See diagnosis and repair.

Browser voice can resume unheard approved replies after navigation. Clients retain per-session mode/mute intent and reconnect with playback receipts; see the voice resume protocol.

Browser replay is available for approved spoken replies before their original recording completes, including interrupted playback. Explicit replay can generate missing audio with the configured TTS provider (normal provider charges apply). See the replay and playback controls.

Safemode investigations

Run claude-gateway safemode --name investigation --prompt "Inspect this gateway problem" for a native interactive Claude Code investigation without stopping the gateway. Use --cli codex to select Codex, --model to override the native model, and --resume investigation to return to the same investigation. Safemode preserves build/startup evidence and uses a separate source snapshot. Session IDs are the native Claude Code/Codex IDs; safemode rename ID NEW_NAME changes the alias without interrupting the conversation. Headless takeover, request IDs and trusted operator agent controls are described in the safemode guide. Trusted agents can discover explicitly assigned investigations and track them as Gateway-managed tasks, with automatic completion reports and conversation-scoped controls.

Paired desktop MCP connectors can also run through Jev as Gateway-managed Computer Use tasks, with local application consent and the same shared Thinking configuration. See Computer Use connectors. Without Jev, Computer Use can instead decide each step with the agent’s own model via gateway.computerUse; see Computer Use without Jev.

Computer Use consent

Computer capability discovery lists paired online computers without requesting access. A Gateway-managed computer task requests access only when it starts. The desktop owner then selects applications (or explicitly selects All applications) and a session duration. Denial prevents execution; pairing and discovery alone never start desktop actions. The task waits for approval with cancellation and ownership checks active, rather than asking the user to pre-enable access in Settings.