Skip to main content
VS Code

​
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)
  2. Python installed at the system level
  3. A Kumo account and API key (Create)
  4. An OpenAI or Anthropic subscription (recommended if you plan to use the Kumo Coding Agent)
  5. Homebrew (macOS package manager) (Install)
  6. GitHub CLI installed and authenticated (required for installing coding-agent skills and some GitHub-powered workflows)
🖥 Terminal 
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: 
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 
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 
pip install kumoai
Verify the installation: 🖥 Terminal 
python -c "import kumoai.experimental.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: 
import os
import kumoai.experimental.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 
python scripts/setup_kumo.py
Manual authentication 
import os
import kumoai.experimental.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 
brew install graphviz
Install the Python package: 🖥 Terminal 
pip install graphviz
Test that a simple graph renders: 
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 
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 AgentThe 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
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
$skill-installer install https://github.com/kumo-ai/kumo-coding-agent
Step 3: Use Codex from VS CodeCodex 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
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): UpgradeUpgrade the KumoRFM SDK🖥 Terminal
pip install --upgrade kumoai
Upgrade the Kumo Coding Agent🖥 Terminal
cd kumo-coding-agent && git pull

​
Step 4: Verify the Setup

Create a minimal script such as scripts/run_prediction.py: 
import os
import kumoai.experimental.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 
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:

​
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 
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 
export KUMO_API_KEY="YOUR_API_KEY_HERE"
Then rerun: 
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