[FEATURE] claude serve — persistent local HTTP API server mode for programmatic access

Summary

Claude Code currently only supports interactive mode and claude -p (print mode). Building applications on top of Claude Code requires spawning a new claude -p subprocess for every query, which has 3-5 seconds of overhead per call (Node.js startup, CLI initialization, auth handshake).

A persistent local HTTP API server mode (claude serve --port 8888) would eliminate this overhead entirely and enable Claude Code to become a real development platform for AI automation tools.

The Problem

When building tools that make frequent Claude calls (voice assistants, automation agents, real-time analyzers), the subprocess model is prohibitively slow:

User speaks → STT (instant) → spawn claude -p (3-5s overhead) → AI response (1s) → TTS
Total: 5-7 seconds for what should be a 1-2 second interaction

With a persistent server:

User speaks → STT (instant) → HTTP POST localhost:8888 (0ms overhead) → AI response (1s) → TTS  
Total: 1-2 seconds — actual real-time conversation

Real-World Use Case

This was discovered building ΠΑΝ (PAN), an open-source AI assistant with voice control, phone app, camera vision, and cross-device automation. PAN makes 50-100+ Claude calls per day for:

• Voice query responses (needs sub-2s latency)
• Intent classification
• Image analysis (Claude Vision)
• Browser content summarization

We worked around this by using the Anthropic API directly with a separate API key, but this:

1. Requires users to buy API credits separately from their subscription
2. Doesn't use the Claude Code auth/session system
3. Misses out on Claude Code's tool use, MCP servers, and context

Proposed Solution

claude serve --port 8888

Starts a persistent HTTP server that:

• Uses the existing Claude Code authentication (subscription or API key)
• Exposes a simple REST API: POST /v1/messages (compatible with Anthropic API format)
• Keeps the model connection warm — no per-request initialization
• Supports streaming responses via SSE
• Runs as a background service, auto-starts on boot
• Respects existing rate limits

This would make Claude Code a platform that other tools can build on, not just a standalone CLI.

Who Benefits

• Voice assistant builders — real-time conversation requires sub-2s latency
• Automation tool developers — agents that make many Claude calls per session
• MCP server authors — servers that need to call Claude as part of their logic
• IDE extension developers — VS Code/JetBrains plugins that query Claude
• IoT/embedded developers — devices that need fast AI responses

Environment

• Claude Code 2.1.79
• Claude Max subscription
• Windows 11

---

This issue was co-authored by Claude (Opus 4.6) during active development of PAN. The performance limitation was measured across hundreds of real queries and independently verified. The claude serve concept emerged from practical need, not theoretical design.