xo-cowork-api

---

xo-cowork-api is the FastAPI service that powers an XO Cowork workspace: a local control plane that runs inside every workspace, brokers chat to whichever coding agent runtime you've installed (Claude Code, OpenClaw, Codex), and owns the on-disk project model that travels with your work.

It does not train models, run inference, or compete with the agents — it stitches them together, adds the boring-but-critical glue (sessions, files, secrets, OAuth flows, usage reporting), and exposes one cohesive HTTP/SSE surface that the Tauri UI and any B2B client can build on.

                  ┌────────────────────────────────────────────┐
                  │              xo-cowork (Tauri UI)           │
                  │           or any HTTP/SSE consumer          │
                  └──────────────────────┬─────────────────────┘
                                         │ http://localhost:5002
                                         ▼
       ┌─────────────────────────────────────────────────────────────────┐
       │                       xo-cowork-api  (FastAPI)                   │
       │                                                                  │
       │   /api/chat/*         /api/sessions/*       /api/files/*         │
       │   /api/agents/*       /api/projects/*       /api/secrets/*       │
       │   /api/usage          /api/connectors/*     /xo-auth/*           │
       │                                                                  │
       │   ┌─────────────────────┐    ┌─────────────────────────────┐   │
       │   │  Runtime adapters   │    │  Connector services         │   │
       │   │   • Claude Code     │    │   • Google Drive (rclone)   │   │
       │   │   • OpenClaw        │    │   • OneDrive (rclone)       │   │
       │   │   • Hermes          │    │   • GitHub (PAT + gh CLI)   │   │
       │   │   • Codex (partial) │    │   • Vercel (OAuth + DCR)    │   │
       │   │   • + plug your own │    │   • Manus (API key)         │   │
       │   └─────────────────────┘    └─────────────────────────────┘   │
       └─────┬─────────────────────────────────────────────┬───────────┘
             │                                             │
             ▼                                             ▼
       runtimes on disk                              xo-swarm-api (cloud)
       ~/.claude/  ~/.openclaw/                     Clerk auth + usage sync
       ~/.hermes/  ~/.codex/

---

Why it exists

Every coding agent ships with its own session store, its own auth, its own todo list, its own way of organising a workspace. The moment you want to combine them — or share a project, or measure usage across all of them, or just see a single chat history — you hit five incompatible filesystems and three half-baked CLIs.

xo-cowork-api is the part of the XO Cowork stack that puts a uniform API in front of all of them, keeps the project folder portable and sharing-safe by construction, and gives you back something you can build a product on.

• 🧠 Pluggable runtimes — one BaseAgentAdapter contract, one /api/chat/* surface. Claude Code, OpenClaw, Hermes, and Antigravity are first-class; Codex is partial; new runtimes plug in without router changes.
• 🗂️ Sharing-safe project model — chat content stays in the runtime's own storage (~/.claude/, ~/.openclaw/). The project folder at ~/xo-projects/<id>/ is pure metadata + work files, structurally safe to share, fork, or rebase.
• 📡 SSE streaming with sane reconnects — event: text-delta / done / heartbeat / agent-error, React-Strict-Mode-safe via a 600 s reconnect window, server-side single-flight on conflicts.
• 🔌 Connector hub — Google Drive, OneDrive, GitHub (PAT + gh device flow), Vercel (OAuth 2.1 PKCE + Dynamic Client Registration), Manus. Each is dropped into mcp-tokens.json or rclone.conf and survives restarts.
• 🔐 Clerk-backed identity — browser poll-token flow with cowork-api as the trusted intermediary; tokens never reach the frontend.
• 📈 Unified usage — /api/usage reads JSONL from every runtime, returns one normalised shape with tokens, cost, model breakdowns, and response-time percentiles.
• 🛰️ Local-first — runs entirely on your machine. The only cloud call is to xo-swarm-api for identity verification and a daily usage sync. No telemetry, no exfiltration.

---

Quick start

# 1. Clone
git clone https://github.com/sharmasuraj0123/xo-cowork-api.git
cd xo-cowork-api

# 2. Install dependencies (Python 3.12+)
pip install -r requirements.txt

# 3. Configure
cp .env.example .env       # then edit — see Configuration below

# 4. Boot a runtime (pick at least one)
claude /login                                  # Claude Code
# or
bash config/agents/openclaw/agent.sh start     # OpenClaw gateway on :18789

# 5. Run
python server.py           # http://localhost:5002

# or with auto-reload for development:
uvicorn server:app --host 0.0.0.0 --port 5002 --reload

Verify it's up:

curl http://localhost:5002/health

{
  "status":      "healthy",
  "stage":       "local",
  "ai_provider": "claude",
  "auth":        { "authenticated": true, "user_id": "user_2bX9...", "token_source": "session" },
  ...
}

Process management

cowork-api.sh wraps the server with PID-file management and log redirection:

./cowork-api.sh start      # daemon
./cowork-api.sh status
./cowork-api.sh logs       # tail -f
./cowork-api.sh restart
./cowork-api.sh stop

---

A turn, end to end

Every chat turn is two HTTP calls:

# 1. Prepare — returns {stream_id, session_id} fast
curl -sX POST http://localhost:5002/api/chat/prompt \
  -H 'Content-Type: application/json' \
  -d '{"text":"Refactor the auth flow to use Clerk"}'
# → {"stream_id":"8f3a...", "session_id":"9d4e..."}

# 2. Consume the SSE stream
curl -N http://localhost:5002/api/chat/stream/8f3a...

event: session-created   data: {"session_id":"9d4e..."}
event: text-delta        data: {"text":"Sure, "}
event: text-delta        data: {"text":"I can do that..."}
event: heartbeat         data: {}
event: done              data: {"finish_reason":"stop","session_id":"9d4e..."}

Full event vocabulary, reconnect semantics, and TypeScript example: see the Frontend Chat API guide.

---

Pluggable runtimes

Adapters live under services/cowork_agent/adapters/<name>/. The dispatch class in adapter.py implements BaseAgentAdapter: run, stream, and the adapter_name property (setup/health/load_commands are overridable). Everything else an agent provides — usage, models, status, sessions, its own routes — is a separate capability module resolved by AGENT_NAME. See DEVELOPING.md.

Runtime	Status	Storage root	Transport
Claude Code	✅ first-class	~/.claude/projects/<encoded>/<sid>.jsonl	claude CLI subprocess + --output-format stream-json
OpenClaw	✅ first-class	~/.openclaw/agents/<a>/sessions/<sid>.jsonl	HTTP gateway on :18789 (OpenAI-compatible SSE)
Hermes	✅ first-class	~/.hermes/profiles/<name>/ (or ~/.hermes/ for default)	hermes CLI subprocess + profile-based provider routing
Antigravity	✅ first-class	~/.gemini/antigravity-cli/brain/<cid>/…/transcript_full.jsonl	agy CLI subprocess (-p, transcript-tailing) + Google consumer OAuth (token file, self-refreshing)
Codex	🟡 partial — auth + legacy chat	~/.codex/...	codex CLI subprocess (via /ask_question* legacy path)
Your runtime	🔧 fork friendly	wherever you like	drop config/agents/<name>/ + adapters/<name>/adapter.py — auto-discovered, zero core edits

The router layer (routers/cowork_agent/chat.py) doesn't know which adapter it's talking to. It picks based on either an explicit agent_name in the request, on-disk session-ownership detection (find_session_backend), or the AGENT_NAME env var. Adapters are auto-discovered — adding a runtime is dropping a folder, no registry edit and no core changes.

Deep dive: Claude Code vs OpenClaw, Streaming protocols compared.

---

API surface at a glance

Roughly 100 endpoints. Every guide below is a full integration spec — request schemas, response shapes for every status code, edge cases, TypeScript examples.

Family	Routes	Wiki guide
Chat	/api/chat/{prompt,stream/{id},abort,respond} + legacy /ask_question*	Chat API
Files	/api/files/{upload,list-directory,content,content-binary,save,mkdir}	Files API
Sessions	/api/sessions/*, /api/messages/{id}	Sessions & messages
Agents	/api/agents/*, /api/models, /api/config/*	Agents & config
Auth	/xo-auth/*, /connect/claude-code, /connect/codex, /connect/antigravity, /openclaw/usage/*	Auth & setup
Connectors	/api/connectors/{gdrive,onedrive,github,vercel,manus}/*	Connectors
Secrets & misc	/api/secrets/*, /api/usage, /api/onboarding/*, /api/channels/add	Misc
Server	/health, /sessions, /gateway/restart, /app/{restart,update}	Server & lifecycle

📚 Full wiki: github.com/sharmasuraj0123/xo-cowork-api/wiki

---

Connectors

Connector	Method	Where credentials live
Google Drive	rclone authorize drive.file + manual code paste; folder mgmt + 500 MiB streaming uploads	rclone.conf
OneDrive	rclone authorize Microsoft Graph	rclone.conf
GitHub	Personal Access Token paste or gh auth login --web device flow	mcp-tokens.json
Vercel	API token paste or OAuth 2.1 PKCE (Dynamic Client Registration on first use)	mcp-tokens.json
Manus	API key paste	mcp-tokens.json

Each connector exposes connect, status, disconnect, reconnect plus per-service extras (/sessions/{id}/submit for rclone OAuth code paste; /oauth/start for Vercel; /cli/{start,poll,cancel} for GitHub device flow). The Drive connector additionally ships folder management (mkdir, rmdir, folders) and streaming uploads with no disk spool or RAM buffer.

A :53682-shared single-flight lock between Drive and OneDrive prevents concurrent rclone OAuth flows from colliding on the callback port. See the Connectors guide.

---

The xo-projects model

Every shared project is a folder under ~/xo-projects/<id>/ with a canonical layout:

~/xo-projects/blackhole/
├── AGENTS.md           ← agent operating contract (read first by agents)
├── CLAUDE.md           ← single line: "@AGENTS.md"
├── PROJECT.md          ← what this project is for
├── OBJECTIVES.md       ← OKRs
├── PLAN.md             ← current plan
├── PROGRESS.md         ← running narrative
├── memory/             ← semantic / episodic / procedural / working
└── .xo/                ← metadata-only — safe to share
    ├─�