Codex

Install the plugin

Use a local Codex session on the machine that will run Space. The server installer supports Linux and macOS; on Windows, use WSL. See the installation requirements.

In your terminal, add the repository's Codex marketplace:

codex plugin marketplace add quirq-ai/xo-space

Then launch Codex and enter /plugins. Select the Quirq marketplace, open the quirq plugin, and install it. Start a new Codex session before using its skills. This follows the repository's Codex plugin README and the official OpenAI plugin instructions.

The repository declares marketplace name quirq-ai in marketplace.json. Its Quirq plugin uses the supported .codex-plugin/plugin.json format and bundles four skills. Installing this bundle makes the instructions available to Codex; it does not install or start the Space server.

Choose a skill

In Codex CLI, enter /skills or type $ to select a skill. You can also ask for a skill by name in a normal prompt. These are the four names shipped by the plugin:

Codex loads a skill when you select it or when your request matches its description. See OpenAI's skill invocation guide.

Check local Space

Send this prompt:

Use the quirq-status skill to check my local Space.

Discovery reads the install pointer at ~/.config/quirq/install.json (or under XDG_CONFIG_HOME), probes /health on the recorded port and then ports 5002/5003, and checks the current directory for a checkout. It does not scan the entire filesystem or change the server's state.

When Space is running, the status skill also reads /health and /api/runtime-config to report its port, stage, authentication state, active sessions, and project/state roots.

Install a Space

Choose the workspace directory yourself and include its absolute path:

Use the quirq-install skill to install Space in /absolute/path/to/workspace.

The skill first checks for an existing installation. If it finds one, it reports that installation instead of reinstalling over it. Otherwise it presents the chosen directory and the installation steps for your confirmation, including creating the directory if needed.

After confirmation, Codex runs the official installer from that directory, prepares the Python environment, and starts the server as a background task of the session. On success it reports the /space/ URL, the log at <workspace>/.quirq/quirq.log, and configuration at <workspace>/xo-space/.env. The bundled install skill defines this sequence.

Start an existing installation

Use the quirq-start skill to start my installed Space.

The skill discovers the checkout, checks that its Python environment exists, and runs the current files on disk. It reports the URL if Space is already running. It does not fetch changes or rerun the installer. To update, use the separate update instructions.

Permissions and server lifetime

Checking status is read-only. Installation and startup need your explicit authorization; choosing a workspace directory is your decision. Codex's own sandbox and approval policy still apply when a skill runs commands. The plugin directs credentials and OAuth setup to Space's Setup and Connectors pages.

The install/start skills run the server as a background task of the current Codex session. They do not create an operating-system service. The server can stop when that session ends or the task is killed; use quirq-start in a later session. For a server you manage independently, follow Install Space in your own terminal.

These behaviors come from the Quirq lifecycle skill and start skill. OpenAI's plugin permissions guide describes the host-level controls.

Troubleshooting

Once Space is running, continue with Your First Space. The Codex Quirq plugin contains the four lifecycle skills above; project creation and the shared todo workflow are covered separately by the xo-projects skill.