Skip to main content

​
Overview

Sphinx is designed to work directly with Jupyter notebooks in VS Code. It can create new notebooks, add and edit cells, execute code, and understand your notebook’s current state—all while you remain in control of what gets executed.

​
Getting Started

​
Open a Notebook

  1. Open any .ipynb file in VS Code
  2. Press Cmd+T (macOS) or Ctrl+T (Windows/Linux) to open Sphinx
  3. Start chatting—Sphinx will work directly in your notebook

​
Create a New Notebook

You can ask Sphinx to create a notebook even without one open:
  1. Open the Sphinx panel with Cmd+T / Ctrl+T
  2. Describe your task (e.g., “Analyze the sales data in data/sales.csv”)
  3. Sphinx will create a new notebook and start working
If you already have a notebook open, Sphinx works in that notebook. Otherwise, it creates a new one in your workspace.

​
Cell Operations

Sphinx can perform four primary operations on notebook cells:

​
Add Cell

Sphinx adds new cells when:
  • Loading data
  • Creating visualizations
  • Processing or transforming data
  • Building models
  • Fetching data from URLs or APIs
┌─────────────────────────────────────┐
│ # Load and explore the dataset      │
│ import pandas as pd                 │
│                                     │
│ df = pd.read_csv('data/sales.csv')  │
│ df.head()                           │
└─────────────────────────────────────┘
          ↓ Sphinx adds cell
┌─────────────────────────────────────┐
│ # Check for missing values          │
│ df.isnull().sum()                   │
└─────────────────────────────────────┘
Cells can be:
  • Code cells — Python code that gets executed
  • Markdown cells — Documentation and explanations

​
Edit Cell

Sphinx edits existing cells when:
  • Fixing bugs or errors
  • Updating visualizations
  • Changing parameters
  • Responding to user corrections
When a cell fails and you provide a correction (like a file path or variable name), Sphinx edits the failed cell rather than creating a new one.
Sphinx can make:
  • Targeted replacements — Small, precise changes to specific lines
  • Complete rewrites — Full cell replacement for major changes

​
Execute Cell

Sphinx executes cells to:
  • Run newly added code
  • Re-run cells after edits
  • Execute cells you explicitly request
When Sphinx executes a cell that updates variables, it automatically considers executing downstream cells that depend on those variables.

​
Delete Cell

Sphinx deletes cells only when you explicitly request it. It won’t remove cells on its own.

​
What Sphinx Sees

Before each interaction, Sphinx extracts context from your kernel to understand your notebook’s current state:
ContextWhat Sphinx Learns
DataFramesNames, shapes, column types, and sample rows (first 3 rows)
VariablesAll variable names and their types
ImportsWhich modules you’ve imported
PackagesInstalled packages and versions
EnvironmentAvailable environment variable names
WorkspaceCurrent working directory
This context helps Sphinx:
  • Reference your existing variables correctly
  • Know which packages are available
  • Understand your data structures
  • Avoid redefining things you’ve already created
Sphinx sees up to 300 variables from your kernel. If you have many temporary variables, consider cleaning them up to give Sphinx clearer context.

​
Execution Flow

Here’s what happens when you ask Sphinx to do something: 
┌──────────────────────────────────────────────────────────┐
│ 1. You send a message                                    │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│ 2. Sphinx extracts kernel context                        │
│    (dataframes, variables, imports, packages, etc.)      │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│ 3. Sphinx reads your notebook cells and outputs          │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│ 4. Sphinx generates code and decides on actions          │
│    (add cell, edit cell, execute, etc.)                  │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│ 5. Actions are applied to your notebook                  │
│    (may require approval in Safe Mode)                   │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│ 6. Sphinx observes execution results                     │
│    (outputs, errors, new variables)                      │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│ 7. Sphinx continues or completes based on results        │
└──────────────────────────────────────────────────────────┘

​
Operation Modes

Sphinx has three operation modes that control how much autonomy it has:

​
Safe Mode

Every code cell requires your approval before execution.
  • Best for: Learning, sensitive environments, understanding what Sphinx does
  • You control: Every cell execution
  • Sphinx does: Generate code, wait for approval

​
Agent Mode (Default)

Sphinx executes code automatically unless a guardrail flags it.
  • Best for: Productive workflows, routine analysis
  • You control: Flagged operations (file writes, installs, etc.)
  • Sphinx does: Execute most code autonomously

​
Plan Mode

Sphinx creates a multi-step plan, gets your approval, then executes.
  • Best for: Complex tasks, when you want to review the approach first
  • You control: The overall plan before execution begins
  • Sphinx does: Plan, then execute after approval
You can switch modes using the dropdown in the Sphinx chat panel.

​
Exploratory vs. Progress Cells

Sphinx distinguishes between two types of cells:
TypePurposeExample
ExploratoryUnderstanding data, checking schemadf.info(), df.describe()
ProgressMoving toward the goalProcessing data, building models
This distinction helps Sphinx:
  • Decide whether to keep or clean up cells
  • Understand what’s essential vs. investigative
  • Optionally collapse exploratory cells (see Settings)

​
Handling Errors

When code fails, Sphinx:
  1. Reads the error — Analyzes the traceback and error message
  2. Identifies the cause — Determines what went wrong
  3. Fixes the issue — Edits the failing cell with a correction
  4. Re-executes — Runs the fixed code
If Sphinx can’t determine the cause, it will ask you for clarification.
If you know what went wrong, tell Sphinx directly: “The file is actually at data/2024/sales.csv” — this helps Sphinx fix the issue faster.

​
Runtime Management

​
Long-Running Cells

For cells that take time to execute, Sphinx:
  • Shows execution time in the cell status
  • Can interrupt cells that run longer than expected (if enabled)
  • Waits for completion before continuing

​
Kernel Sessions

Sphinx works with your notebook’s kernel session:
  • Uses whatever kernel you’ve selected (local, remote, cloud)
  • Shares the kernel state with any cells you run manually
  • Variables persist across Sphinx interactions and manual executions

​
Checkpoints

When using Agent Mode, Sphinx automatically creates checkpoints of your notebook before making changes. This lets you:
  • Restore previous versions if something goes wrong
  • Review what changed between checkpoints
  • Undo Sphinx’s changes by restoring a checkpoint
Checkpoints can be disabled in VS Code settings if you want to reduce disk usage.

​
Best Practices

1

Start with data loading

Begin your session by loading your data. This gives Sphinx context about your dataframes from the start.
2

Run cells to establish context

If you have existing code, run the cells so Sphinx can see your variables and data structures.
3

Be specific about what you want

Instead of “analyze this data”, try “create a bar chart showing sales by region, sorted by total sales”.
4

Provide corrections directly

When something fails, tell Sphinx the fix: “The column is called ‘sale_date’, not ‘date’”.
5

Use markdown for documentation

Ask Sphinx to add markdown cells explaining your analysis—great for sharing notebooks later.