> ## Documentation Index
> Fetch the complete documentation index at: https://kumo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> Use Codex with the Kumo RFM SDK

<img src="https://mintcdn.com/kumoai/sauZu1594eNyXDA7/images/rfm/agent-chatgpt.svg?fit=max&auto=format&n=sauZu1594eNyXDA7&q=85&s=67194333a1fd18b1872d6fde43a15b1c" alt="Codex" style={{height: "100px", width: "auto"}} width="320" height="320" data-path="images/rfm/agent-chatgpt.svg" />

## Overview

This guide walks you through setting up the **KumoSDK** and **Kumo Coding Agent** with **OpenAI Codex** in desktop and CLI environments.

Codex is an AI coding agent by OpenAI. It can read your project files, write code, run commands, and iterate on errors. You interact with it by typing natural language prompts.

## Prerequisites

Make sure you have:

1. Python **3.10 to 3.13** installed
2. Access to a KumoRFM environment, including an API key and any required API URL
3. An OpenAI account (ChatGPT or API)
4. Codex installed and authenticated. See the [official Codex docs](https://developers.openai.com/codex) for desktop app and CLI installation.

## Step 1: Create a Project

Create or open a project directory:

```bash theme={null}
mkdir my-kumo-project
cd my-kumo-project
```

**Desktop app:** Open Codex and select your project folder.

**CLI:** Navigate to your project in the terminal.

## Step 2: Install KumoSDK

```bash theme={null}
pip install kumoai
```

Verify:

```bash theme={null}
python -c "import kumoai; print(f'kumoai {kumoai.__version__} installed')"
```

## Step 3: Authenticate with Kumo

Set your API key:

```bash theme={null}
export KUMO_API_KEY="YOUR_API_KEY_HERE"
```

## Step 4: Install Kumo Coding Agent

The Kumo Coding Agent has two parts:

* **Context** (knowledge base): Documentation, PQL rules, workflow guides, and data connector references that teach the agent how to use the Kumo platform. Installed by cloning the repository.
* **Skills** (slash commands): Actions like `/kumo-issue` and `/kumo-pr` for reporting bugs and contributing fixes. Installed via the skill installer.

**Install the context:**

```bash theme={null}
git clone https://github.com/kumo-ai/kumo-coding-agent.git kumo-coding-agent
echo 'Also read kumo-coding-agent/CLAUDE.md for Kumo agent capabilities.' >> AGENTS.md
```

The second line adds the agent to your project's `AGENTS.md`, which Codex reads automatically on startup.

**Install the skills (optional).**

Open a Codex session (see Step 5) and type:

```text theme={null}
$skill-installer install https://github.com/kumo-ai/kumo-coding-agent
```

## Step 5: Use the Kumo Coding Agent

**Desktop app:**

1. Open the Codex desktop app
2. Select your project folder
3. Type a prompt in the chat panel at the bottom:

```text theme={null}
Load the RelBench F1 dataset and predict whether each driver will finish in the top 3 in the next race
```

4. Codex will read the Kumo Coding Agent context, inspect the data, build a graph, write PQL, and run the prediction.
5. Review the changes Codex proposes and approve them.

**CLI:**

Run a prompt directly from the terminal:

```bash theme={null}
codex "Load the RelBench F1 dataset and predict whether each driver will finish in the top 3 in the next race"
```

Codex will generate files, run code, and output results in the terminal.

<Info>
  Codex runs headless in CLI mode. Provide the full prompt upfront. For multi-step workflows, run Codex multiple times or use the desktop app for interactive sessions.
</Info>

## Step 6 (Optional): Upgrade

**Upgrade KumoSDK:**

```bash theme={null}
pip install --upgrade kumoai
```

**Upgrade the Kumo Coding Agent:**

```bash theme={null}
cd kumo-coding-agent && git pull
```

To pin to a specific version:

```bash theme={null}
cd kumo-coding-agent && git checkout v1.0.0
```

## Troubleshooting

### `kumoai` cannot be imported

```bash theme={null}
pip install kumoai
```

### API key is missing

```bash theme={null}
export KUMO_API_KEY="YOUR_API_KEY_HERE"
```

### Agent does not respond with Kumo knowledge

* Verify `kumo-coding-agent/` exists in your project directory
* Verify your project's `AGENTS.md` contains the line referencing `kumo-coding-agent/CLAUDE.md`
* Restart Codex or open a new session

### Codex CLI not found

```bash theme={null}
npm install -g @openai/codex
```

## Next Steps

* [Setup](/rfm/sdk-getting-started) for SDK fundamentals
* [Make Predictions](/rfm/make-predictions) for PQL query reference
* [Kumo Coding Agent](https://github.com/kumo-ai/kumo-coding-agent) for agent source and skills