Contributing to XO Space

xo-space is the open-source local control plane service for AI coding agents. It stitches together runtimes (Claude Code, OpenClaw, Hermes, Antigravity, Codex, Cursor), manages workspace project metadata, and serves the browser UI at /space/.

Core Invariants

When contributing to xo-space, uphold the following four architectural invariants:

1. The Modularity Invariant: Core code is agent-agnostic. No core file (server.py, routers/, services/engine/) may name a specific agent backend. Agent-specific code lives exclusively in config/agents/<name>/ and services/cowork_agent/adapters/<name>/.
2. The Project Folder is Sacred: Never write chat transcripts, session messages, or secrets into a project directory or <XO root>/<project>/.xo/. Conversations remain strictly in the runtime's native storage (~/.claude/, ~/.openclaw/, ~/.hermes/, ~/.gemini/antigravity-cli/, ~/.codex/).
3. .xo/ Belongs to the Watcher: Only services/cowork_agent/visualizer/{sinks,workspace}/ writes to .xo/ directories. All other services and UI endpoints read derived state.
4. Thin Routers, Logic in Services: Endpoints defined in routers/ act as thin HTTP request/response handlers; business logic lives in services/.

Development Setup

git clone https://github.com/quirq-ai/xo-space.git
cd xo-space

# Create virtual environment and install dependencies
./cowork-api.sh install

# Runs FastAPI with hot reloading on port 5002 (falls back to 5003 if busy)
./cowork-api.sh dev

AGENT_NAME=claude_code venv/bin/python server.py
# or: AGENT_NAME=hermes, AGENT_NAME=openclaw, AGENT_NAME=antigravity

Adding a New Agent Backend ("Drop Two Folders")

Adding a new coding agent requires zero changes to core router files.

from services.cowork_agent.adapters.base import BaseAgentAdapter

class MyAgentAdapter(BaseAgentAdapter):
    @property
    def adapter_name(self) -> str:
        return "my_agent"

    async def run(self, question: str, session_id: str | None = None, **kwargs):
        # One-shot command execution
        ...

    async def stream(self, prompt: str, session_id: str | None = None, **kwargs):
        # Asynchronous SSE token streaming
        ...

Adapter = MyAgentAdapter

Validation Playbook

Run the test suite and validation gates before submitting a Pull Request:

# 1. Run unit test suite (94 tests across 14 modules)
venv/bin/python -m unittest discover -s tests -t .

# 2. Test import gates across all agent backends
for a in claude_code openclaw hermes antigravity; do
  AGENT_NAME=$a venv/bin/python -c "import server; \
    print('$a', len(server.app.openapi()['paths']))"
done

# 3. Check Claude & Codex plugin synchronization
./scripts/check_plugin_sync.sh

Pull Request Guidelines

• Target Branch: Target main for all features and fixes.
• Documentation: If your change modifies the adapter contract, .xo/ schema, or /xo/*.json views, update DEVELOPING.md and space_ui/js/views/wiki.js in the same commit.
• Backward Compatibility: Preserve existing endpoint schemas and response shapes.
• No Secret Logging: Never log API tokens, user prompt text, or authentication cookies.