xo-space

One environment for Claude Code, Codex, OpenClaw, Hermes and Antigravity. Every project, session, todo and cost on one screen. Measure output, not just tokens.

Quick start · Capabilities · Supported agents · How it works · Docs · Contributing

---

The problem

Every coding agent keeps its own session store, its own auth, its own todo list and its own idea of what a "project" is. Use two of them on the same codebase and you have two histories, two usage bills and no single place to look. And none of them tell you what was actually delivered — only what was spent.

What XO Space is

XO Space is the environment layer between your machine and your agents: a local server (this repository) that sits in front of the agents you already have installed, plus a browser UI that reads what they do. It does not run models or replace the agents. It stitches them together and measures what they deliver.

curl -fsSL https://quirq.ai/install | sh      # then open http://localhost:5002/space/

---

Key capabilities

• 👀 Watch your agents work — see which agent is active in which project right now, what it touched, and what it's been doing session by session.
• 🗂️ Your whole workspace in one place — every folder is a project. Files, git history, todos and live agent activity, browsable from one screen instead of five terminals.
• ✅ Manage the work, not the chat — todos per project, kept up to date as agents check them off, so you always know what's done and what's next.
• 🔌 One API for every agent — POST /api/chat/prompt, read an SSE stream. Same contract whether Claude Code, Codex, OpenClaw, Hermes or Antigravity is behind it; switch with one environment variable.
• 📡 Sessions across runtimes — session telemetry from every agent that exposes it, side by side, whichever one you're chatting with.
• 📈 Know what it cost — tokens, cost, per-model and per-tool breakdowns in one shape regardless of runtime.
• 🕰️ See how it grew — every project's git history in parallel lanes; open any commit as a 3D city map where building height is the churn.
• 🛰️ Local-first — binds to localhost, needs no account, sends nothing until you sign in. What leaves your machine.

---

Quick start

Install in Codex

Add this repository to Codex once:

codex plugin marketplace add quirq-ai/xo-space

Open Plugins → Quirq → XO Space → Install, start a new task, and say “Open XO Space.” Codex installs and starts Space in ~/xo-workspace (or the workspace you name), selects the Codex backend, and opens the UI. Existing installations keep their settings. The server runs while its task/terminal stays alive. Plugin setup, prerequisites and development-branch installs.

One-click setup

Run this from the directory you want as your workspace — each sub-folder becomes a project:

curl -fsSL https://quirq.ai/install | sh

Then open http://localhost:5002/space/.

What the installer does: clones this repo into ./xo-space, creates a Python 3.12 venv with uv, and starts the server in the foreground. Ctrl-C stops it; re-running the command updates and restarts it. Machine-local state and logs live in ./.quirq/, next to your projects — including logs/quirq.log for server output and inbox/activity/commands.log for every external command Quirq runs in that state root — and the whole install is one folder you can move or delete. For a clean removal that keeps your project folders, run ./xo-space/uninstall.sh — see INSTALLATION.md.

Requirements: git. Everything else is optional and only disables its own feature — node/npm for installing an agent CLI, gh for project backup, rclone for Drive/OneDrive. Windows runs under WSL (details).

Manual setup

Same result, step by step — if you'd rather see what you're running, or you're going to hack on it:

# 1. Clone
git clone https://github.com/quirq-ai/xo-space && cd xo-space

# 2. First run — detects the checkout, uses it in place, writes ./.env with
#    working defaults, and starts the server. Ctrl-C when you've seen it.
./install.sh

# 3. Configure — edit .env to taste (see the table below), then run again
./install.sh

.env is written once and never rewritten, so your edits survive updates. Values exported in your shell win over the file (PORT=8080 ./install.sh). The keys it contains:

Key	What it does	Default
AGENT_NAME	Which agent handles chat: claude_code, codex, openclaw, hermes, antigravity, grokbot	claude_code
XO_PROJECTS_ROOT	Your workspace — the directory whose sub-folders are projects	the directory you ran the installer from
QUIRQ_STATE_ROOT	Machine-local state: runtime config, saved credentials, watcher cursors, logs. Must not be inside a project	./.quirq in that directory
AI_WORKSPACE_ROOT	The directory the agent subprocess is started in and allowed to touch	same as XO_PROJECTS_ROOT
HOST, PORT	Where the server listens. Loopback only by default. The API has no login, so HOST=0.0.0.0 lets every device on your network read and change your files: use it only on a network you trust	127.0.0.1, 5002
STAGE	local finds agent CLIs with which; beta assumes the hosted container layout	local
QUIRQ_WATCHER_SOURCE_MODE	all — the watcher reads every installed agent's session store, so Sessions shows all of them; active — only AGENT_NAME's	all
QUIRQ_SKIP_BOOT_INSTALL	1 — install nothing beyond requirements.txt. Set 0 to let boot hooks apt/nvm/npm -g the agent CLI for you	1
UVICORN_RELOAD	Auto-restart on code changes — turn on when hacking on the server	false
ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN	Optional. The agent CLI normally uses its own login; set one only if it isn't already authenticated. Leave commented rather than blank	unset
XO_API_KEY	Links this install to your XO account	unset

Agent-specific knobs (CLAUDE_CLI_PATH, CODEX_CLI_PATH, the OpenClaw/Hermes gateway URLs and tokens, Google Drive/Vercel connector settings) are documented in .env.example. Roots, the state directory and watcher timing: INSTALLATION.md.

First run. Space opens on Projects → Overview (#/projects/overview). Projects contains Overview | Data | Timeline | Manage, with List | Graph | Tree views inside Data. Choose Data → List (#/projects/data/list) to browse the folders in your workspace, or open Manage → Add project to clone a Git repository. Before the first chat, check Setup → Intelligence layer for the agent connection and activity collection settings. Full walkthrough: INSTALLATION.md.

Finding your projects. Search by name, folder ID or description, filter to Live sessions or Pinned projects, and sort by recent activity, name, indexed files or creation date. Pin projects from Manage; pins stay in this browser and appear in Data’s Pinned filter. Open a Data List row to browse files; folder position and filters survive navigation, and Refresh files rereads the current folder. File counts describe the visible file index, with + when scanning was incomplete; a project missing from the index shows Not indexed. Graph root, available throughout Projects, opens the graph at the chosen node.

Managing projects. Projects → Manage (#/projects/manage) contains cloning, inline sharing and guarded local removal. Each card groups View activity, Share, Pin, Copy GitHub URL and Remove in its header. Expand a card to view its metadata and GitHub Issues and copy recorded values. To share, enter the destination Space ID in the card without leaving Manage. Individual access must be revoked before a shared project can be deleted locally. The old #/setup/projects address opens Manage.

Inbox and activity. Inbox contains Items | Connections | Jobs | Activity | Sharing activity | Sharing. Activity shows project events; select a project for its todos and current sessions. Sharing activity shows the relay's recent events, while Sharing manages repository access and synchronization.

Setup. Workspace and Intelligence layer guide initial configuration. Workspace shows the Space ID, workspace owner, XO account and verified GitHub identity. Connectors, Secrets, Commands and Server provide app connections, environment keys, saved commands/results and server controls. Direct URLs are #/setup/workspace, #/setup/intelligence, #/setup/connectors, #/setup/secrets, #/setup/commands and #/setup/server. Opening Setup starts at Workspace; existing #/setup, #/connectors and #/secrets links remain compatible.

Search Setup to find a setting and jump to its control. Connectors includes GitHub, MagicPath, Vercel, Google Drive and OneDrive alongside account apps, with connection status and the existing sign-in and management actions.

XO Managed Cloud

Don't want to run a server? app.xo.builders gives you the same XO Space, already running, in an XO-provisioned workspace — one click, nothing to install, your agents and projects ready when you open the tab.

	Self-hosted	XO Managed Cloud
Runs on	your machine	XO-provisioned workspace
Setup	one command, you keep it running	none — always on
Account & sign-in	optional	built in
Updates	re-run the installer	automatic
Sharing projects with a team	via GitHub backup	built in
Code	this repo	this repo

---

Supported agents

Pick the active agent with AGENT_NAME (or from the Setup tab). Agents that expose session telemetry show up in the Agents tab even when they are not the active one.

Agent	AGENT_NAME	Chat	Sessions	Notes
Claude Code	claude_code	✅	✅	claude CLI subprocess
Codex	codex	✅	✅	codex exec subprocess
OpenClaw	openclaw	✅	✅	HTTP gateway on :18789; the default when nothing is configured
Hermes	hermes	✅	✅	HTTP gateway on :8642, one per profile
Antigravity	antigravity	✅	✅	agy CLI subprocess + Google OAuth
Grok Bot	grokbot	partial	partial	External host gateway on :1340; replies arrive after polling. Text history comes from the gateway for Space-indexed chats. No Space project/MCP/model selection, usage, status integrations, Agents management, telemetry or prompt suggestions. See Grok Bot limits.
Cursor	—	—	✅	Read-only: sessions appear in telemetry, cannot run a turn
Your own	<name>	✅	✅	Drop config/agents/<name>/ + services/cowork_agent/adapters/<name>/ — auto-discovered, no core edits. Guide: DEVELOPING.md §4

Grok Bot limits

Set AGENT_NAME=grokbot and run the host separately. The gateway defaults to http://127.0.0.1:1340 (GROKBOT_GATEWAY_URL, alias SAND_GATEWAY_URL); chat needs SAND_GATEWAY_TOKEN or the token in sand-data/gateway.json. The community SDK documents the gateway protocol; it is not a host installer. Space