agent-api

An OpenAI Responses-API-compatible shim that serves Muse (a personal AI assistant) as a stateless HTTP API, so it can be used as a model backend for Claude Code via CLIProxyAPI.

The core semantic: Claude Code owns the multi-turn agentic loop. Each HTTP request to this bridge is exactly one model turn, handled by one stateless worker. The bridge never accumulates conversation state.

Architecture

Claude Code → CLIProxyAPI → POST 127.0.0.1:8787/v1/responses
    │
    ▼
server.py ── writes queue/<resp_id>.json ── long-polls (≤900s) for responses/<resp_id>.json
    │
    ▼
dispatcher (persistent subagent) ── watches queue/ ── spawns ONE worker subagent per file
    │
    ▼
worker (single-use subagent) ── reads ONLY its request file ── writes OpenAI
    response object to responses/<resp_id>.json ── exits
    │
    ▼
server.py returns the response as JSON, or as SSE when "stream": true

Workers never execute tools. They emit function_call items; Claude Code / CLIProxyAPI executes them and sends results back as function_call_output in a follow-up request.

Per-request overhead is ~5–10s fixed (LLM inference steps: dispatcher notice + worker spin-up), regardless of task size. Floor is ~3–5s — this is a property of the agent harness, not the plumbing. Irrelevant for long agentic turns; noticeable for rapid-fire trivial calls.

Quickstart

./scripts/bootstrap.sh   # (re)start the server
./scripts/status.sh      # health overview

# smoke test
curl -s -X POST http://127.0.0.1:8787/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{"model":"muse-spark","input":"Reply with exactly: SMOKE_OK","max_output_tokens":30}'

The dispatcher is supervised automatically (see "Supervision" below) — no manual step needed.

File map

Path	What it is
server.py	HTTP server: POST /v1/responses, GET /v1/models, GET /health. Model id muse-spark.
DISPATCHER.md	Brief for the persistent dispatcher subagent (queue watcher, worker spawner).
WORKER_PROMPT.md	Brief for single-use workers (context isolation, response format, must-write rule).
scripts/bootstrap.sh	(Re)start the server with logging.
scripts/status.sh	Health overview: server, dispatcher liveness, queue depths.
archive/	Retired designs (the pre-warmed pool experiment).
queue/, `pro