> ## 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.
# VS Code + Kumo Agent
> Set up VS Code with the Kumo coding agent
## Overview
This guide walks you through setting up the **KumoRFM SDK** and **Kumo Coding Agent** for use with **KumoRFM** in a **VS Code** project workflow.
Unlike the notebook-based setup, this guide focuses on working with regular Python files, the VS Code integrated terminal, and coding-agent workflows that edit scripts, configuration, and project files directly.
This guide assumes minimal prior experience with VS Code, Python virtual environments, and coding agents. If you already have a preferred local setup, you can jump directly to the relevant sections.
## Prerequisites
Make sure you have:
1. VS Code installed ([Download](https://code.visualstudio.com/download))
2. Python installed at the system level
3. Access to a KumoRFM environment, including an API key and any required API URL
4. An OpenAI or Anthropic subscription (recommended if you plan to use the Kumo Coding Agent)
* **OpenAI Codex** ([Subscribe](https://openai.com/codex))
* **Anthropic Claude Code** ([Subscribe](https://claude.com/product/claude-code))
5. Homebrew (macOS package manager) ([Install](https://brew.sh/))
6. GitHub CLI installed and authenticated (required for installing coding-agent skills and some GitHub-powered workflows)
`🖥 Terminal`
```bash theme={null}
brew install gh
gh auth status
gh auth login
```
## Part 1: Setup for VS Code + KumoRFM SDK
### Step 1: Create or Open a Project Folder
Start with a normal VS Code project folder rather than a notebook file.
1. Open **VS Code**
2. Choose **File -> Open Folder**
3. Create or open a project directory such as `kumo-demo`
A simple starter structure works well:
```text theme={null}
kumo-demo/
├── .venv/
├── data/
├── scripts/
├── models/
└── README.md
```
Keeping your data, scripts, and generated outputs in one project folder makes it much easier for Codex or Claude Code to understand your workflow.
### Step 2: Create a Python Virtual Environment
Open the VS Code integrated terminal:
* Use **Terminal -> New Terminal**
* Or press `Ctrl + backtick`
Then create a virtual environment inside the project:
`🖥 Terminal`
```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
```
If VS Code prompts you to select a Python interpreter, choose the one from your local `.venv` directory.
You can also manually choose it:
1. Open the **Command Palette** (`Cmd + Shift + P`)
2. Search for `Python: Select Interpreter`
3. Select the interpreter inside `.venv`
### Step 3: Install the KumoRFM SDK
Install the SDK inside the active virtual environment:
`🖥 Terminal`
```bash theme={null}
pip install kumoai
```
Verify the installation:
`🖥 Terminal`
```bash theme={null}
python -c "import kumoai.rfm as rfm; print('Kumo SDK loaded successfully')"
```
### Step 4: Authenticate the KumoRFM SDK
You need an API key before you can make calls to KumoRFM.
There are two common approaches:
* use interactive authentication
* set `KUMO_API_KEY` manually
**Interactive authentication**
Create a small setup script such as `scripts/setup_kumo.py`:
```python theme={null}
import os
import kumoai.rfm as rfm
if not os.environ.get("KUMO_API_KEY"):
rfm.authenticate()
rfm.init(api_key=os.environ.get("KUMO_API_KEY"))
print("Kumo SDK initialized successfully")
```
Run it from the integrated terminal:
`🖥 Terminal`
```bash theme={null}
python scripts/setup_kumo.py
```
**Manual authentication**
```python theme={null}
import os
import kumoai.rfm as rfm
os.environ["KUMO_API_KEY"] = "YOUR_API_KEY_HERE"
rfm.init(api_key=os.environ.get("KUMO_API_KEY"))
```
### Step 5: Optional Dependencies
Install Graphviz if you want to visualize graphs from a script-based workflow.
Install the system dependency:
`🖥 Terminal`
```bash theme={null}
brew install graphviz
```
Install the Python package:
`🖥 Terminal`
```bash theme={null}
pip install graphviz
```
Test that a simple graph renders:
```python theme={null}
from graphviz import Digraph
g = Digraph()
g.edge("Users", "Orders")
g
```
## Part 2: Using the VS Code CLI Workflow
The VS Code integrated terminal is one of the easiest ways to work with the KumoRFM SDK in an editor-based workflow.
Instead of switching between separate apps, you can keep all of the following in one place:
* your Python scripts
* your terminal commands
* your coding agent chat panel
* project files such as `README.md`, config files, and sample queries
Common tasks you can run directly from the integrated terminal include:
`🖥 Terminal`
```bash theme={null}
source .venv/bin/activate
python scripts/setup_kumo.py
python scripts/run_prediction.py
```
This workflow works especially well when:
* you want reproducible scripts instead of interactive notebook cells
* you want Codex or Claude Code to edit source files directly
* you want to commit your work to Git as normal Python code
* you want to run the same setup locally, in CI, or on another machine
A good pattern is to keep small entry-point scripts in `scripts/` and ask the coding agent to edit those files rather than generating one-off terminal commands each time.
## Part 3: Add a Coding Agent (Optional)
Choose **one** of the following to add an AI coding agent to your workflow:
**Step 1: Install the VS Code Extension**
1. Open VS Code Extensions (`Cmd + Shift + X`)
2. Search for **"Codex - OpenAI's coding agent"**
3. Install the extension
**Authenticate:**
* Sign in with ChatGPT (recommended)
* Or configure `~/.codex/config.toml`
**Open Codex using:**
* the ChatGPT icon in the top-right corner added by the extension
Reload VS Code if the extension does not appear immediately.
**Step 2: Install the Kumo Coding Agent**
The Kumo Coding Agent has two parts:
* **Context** (knowledge base): documentation, PQL rules, workflow guides, and connector references that teach the agent how to use the Kumo platform
* **Skills** (slash commands): actions like `/kumo-issue` and `/kumo-pr` for reporting bugs and contributing fixes
**Install the context**
`🖥 Terminal`
```bash theme={null}
cd your-project
git clone https://github.com/kumo-ai/kumo-coding-agent.git kumo-coding-agent
```
This action adds a directory named `kumo-coding-agent` to your project. It contains the Kumo Coding Agent's knowledge base. Confirm that this directory appears in your project.
Codex reads `AGENTS.md` automatically. No extra configuration is required.
**Install the skills (optional)** inside a Codex session:
`🤖 Codex`
```text theme={null}
$skill-installer install https://github.com/kumo-ai/kumo-coding-agent
```
**Step 3: Use Codex from VS Code**
Codex works especially well in VS Code when you ask it to edit files in your project instead of isolated notebook cells.
Good requests include:
`🤖 Codex`
```text theme={null}
Create a scripts/run_prediction.py file that loads the RelBench F1 dataset,
builds a Kumo graph, and predicts whether each driver will finish in the
top 3 in the next race.
```
You can also use Codex to:
* add or update Python scripts
* create `requirements.txt` or `README.md` files
* draft PQL queries
* help debug terminal errors from your local environment
The integrated terminal is still where you run Python scripts and other shell commands. Codex helps generate and edit the files, but you remain in control of executing the workflow locally.
**Step 4 (Optional): Upgrade**
**Upgrade the KumoRFM SDK**
`🖥 Terminal`
```bash theme={null}
pip install --upgrade kumoai
```
**Upgrade the Kumo Coding Agent**
`🖥 Terminal`
```bash theme={null}
cd kumo-coding-agent && git pull
```
**Step 1: Install the VS Code Extension**
1. Open VS Code Extensions (`Cmd + Shift + X`)
2. Search for **"Claude Code"** (by Anthropic)
3. Install the extension
**Authenticate:**
* Sign in with your Anthropic account when prompted
**Open Claude Code using either:**
* the Anthropic spark icon in the sidebar
* the Anthropic spark icon in the top-right corner
* `Cmd + Shift + P` -> `Claude Code: Open`
Reload VS Code if the extension does not appear immediately.
**Step 2: Install the Kumo Coding Agent**
The Kumo Coding Agent has two parts:
* **Context** (knowledge base): documentation, PQL rules, workflow guides, and connector references that teach the agent how to use the Kumo platform
* **Skills** (slash commands): optional helpers installed with `npx skills add`
**Install the context**
`🖥 Terminal`
```bash theme={null}
cd your-project
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.' >> CLAUDE.md
```
This action adds a directory named `kumo-coding-agent` to your project. It contains the Kumo Coding Agent's knowledge base. Confirm that this directory appears in your project.
The second line tells Claude Code to read the agent's knowledge base when it starts.
**Install the skills (optional)**
To run the following command, you need Node.js installed on your system:
`🖥 Terminal`
```bash theme={null}
npx skills add kumo-ai/kumo-coding-agent --agent claude-code
```
**Step 3: Use Claude Code from VS Code**
Claude Code works best in VS Code when you ask it to reason over the full project, including scripts, prompts, config files, and output files.
Good requests include:
`✨ Claude`
```text theme={null}
Add a scripts/run_prediction.py example that authenticates with Kumo,
loads a local dataset, defines a graph, and runs a simple predictive query.
```
You can also use Claude Code to:
* draft end-to-end example scripts
* explain KumoRFM errors from terminal output
* propose cleaner project structure
* help turn an ad hoc experiment into reusable Python code
Claude Code can update your project files, but you should still run the scripts yourself from the integrated terminal so you can confirm the local environment and outputs are correct.
**Step 4 (Optional): Upgrade**
**Upgrade the KumoRFM SDK**
`🖥 Terminal`
```bash theme={null}
pip install --upgrade kumoai
```
**Upgrade the Kumo Coding Agent**
`🖥 Terminal`
```bash theme={null}
cd kumo-coding-agent && git pull
```
### Step 4: Verify the Setup
Create a minimal script such as `scripts/run_prediction.py`:
```python theme={null}
import os
import kumoai.rfm as rfm
if not os.environ.get("KUMO_API_KEY"):
raise RuntimeError("KUMO_API_KEY is not set")
rfm.init(api_key=os.environ.get("KUMO_API_KEY"))
print("Kumo SDK initialized successfully")
```
Run it:
`🖥 Terminal`
```bash theme={null}
python scripts/run_prediction.py
```
## Run Your First Example
Once the SDK and coding agent are set up, ask the agent to help you scaffold a simple project-based workflow.
Examples:
* create a `LocalGraph` from local data files
* draft a first predictive query in Python
* create a reusable script instead of a one-off notebook
* add logging, comments, and lightweight validation
If you prefer to start from a guided SDK example first, continue with:
* [SDK Getting Started](/rfm/sdk-getting-started)
* [Coding Agent Quick Start](/rfm/coding-agent-quick-start)
## Troubleshooting
### VS Code cannot find the interpreter
* Re-run `Python: Select Interpreter`
* Make sure `.venv` exists in the project folder
* Restart VS Code after creating the environment
### The SDK will not import
`🖥 Terminal`
```bash theme={null}
source .venv/bin/activate
pip install kumoai
```
Then rerun your script.
### The API key is missing
Export the API key before running a script:
`🖥 Terminal`
```bash theme={null}
export KUMO_API_KEY="YOUR_API_KEY_HERE"
```
Then rerun:
```bash theme={null}
python scripts/run_prediction.py
```
### The coding agent edited files, but the workflow still fails
* Re-run the script from the integrated terminal
* Check that the active terminal is using `.venv`
* Review the modified files before rerunning commands
* Ask the agent to fix the error using the exact terminal output
## 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