Follow Active Notebook
By default, Sphinx automatically follows the notebook you’re currently working on. When you switch between notebooks in your editor, Sphinx’s chat panel updates to show the conversation and context for that notebook.
This behavior is managed by a lock toggle in the Sphinx chat panel header:
- Unlocked (default) — Sphinx follows whichever notebook you have active
- Locked — Sphinx stays connected to a specific notebook, even when you switch tabs
Lock the notebook connection when you want to reference one notebook while viewing another, or when running long operations that shouldn’t be interrupted by tab switches.
Collapse Exploratory Cells
When Sphinx explores your data, it often creates intermediate cells to inspect DataFrames, check values, or test approaches. These “exploratory” cells can clutter your notebook.
Collapse Exploratory Cells automatically minimizes these intermediate cells (both input and output) so your notebook stays clean while preserving the exploration history.
Enable Auto-Collapse
Set sphinx.collapse-exploratory-cells to true in your editor settings:
{
"sphinx.collapse-exploratory-cells": true
}
Manual Collapse
You can also collapse exploratory cells on-demand using the Command Palette:
- Open Command Palette (
Cmd+Shift+P / Ctrl+Shift+P)
- Run Sphinx: Collapse Exploratory Cells
Chat History
Sphinx maintains a searchable history of all your conversations across notebooks. This allows you to revisit past analyses, reuse insights, and continue where you left off.
Accessing Chat History
Click the history icon in the Sphinx chat panel header to browse previous conversations. You can:
- Search by keyword across all conversations
- Filter by notebook
- Resume any previous conversation
- View the full conversation thread
How It Works
- Chat history is indexed locally in your workspace
- The index automatically updates every 5 minutes to catch external changes
- Conversations are stored within the notebook file itself (
.ipynb metadata)
Managing Chat History
| Command | Description |
|---|
| Sphinx: Rebuild Chat History Index | Re-index all notebooks in your workspace |
| Sphinx: Clear Chat History Index | Remove the local search index |
| Sphinx: Delete Conversation History | Delete the current conversation |
Checkpoints
Checkpoints automatically save your notebook state before each conversation, allowing you to restore your notebook if something goes wrong.
How Checkpoints Work
- When you start a new conversation, Sphinx saves a checkpoint of your current notebook
- One checkpoint is maintained per notebook (overwritten on each new conversation)
- Checkpoints older than 3 days are automatically cleaned up
- Checkpoints are stored in
~/.sphinx/checkpoints/
Restoring a Checkpoint
If Sphinx makes changes you want to undo, you can restore from the checkpoint:
- Click the restore icon in the chat panel
- Confirm the restoration
- Your notebook returns to its state before the conversation began
Disabling Checkpoints
If you want to save disk space or manage notebook history yourself:
{
"sphinx.enable-checkpoints": false
}
Disabling checkpoints removes the ability to restore your notebook to its pre-conversation state. Consider using version control instead.
@ Mentions
Use @ mentions in the chat input to provide Sphinx with specific context. This helps Sphinx understand exactly what you’re referring to.
Mentioning Cells
Type @ followed by a cell number to reference a specific cell:
@Cell 3 — Reference cell 3 in your notebook- Click on the mention to navigate to that cell
When you mention a cell, Sphinx receives the full cell content and any outputs, giving it precise context for your request.
You can also click on a cell’s status bar (where the cell number appears) to quickly add it as a mention to your current message.
Searching for Files
Type @ to open the file search popup, which lets you:
- Search files in your workspace by name
- Browse recent files you’ve opened
- Reference DataFrames currently loaded in your kernel
When you select a file, Sphinx receives:
- The file path (relative to your workspace)
- For code files: the full file content
- For DataFrames: name, shape, and column information
Mentioning DataFrames
When you have DataFrames loaded in your kernel, they appear in the @ menu. Selecting a DataFrame gives Sphinx:
- The DataFrame name
- Number of rows and columns
- Column names and types
- A sample of the data
Edit with Sphinx
The Edit with Sphinx wand appears on notebook cells, allowing you to quickly ask Sphinx to modify that specific cell.
Using the Edit Wand
- Hover over any code cell
- Click the wand icon (✨) in the cell toolbar
- Type your edit request (e.g., “add error handling” or “use a bar chart instead”)
- Sphinx modifies the cell based on your instructions
Hiding the Wand
If you prefer a cleaner cell interface:
{
"sphinx.show-edit-cell-wand": false
}
@Cell in your chat message.
Sharing Notebooks
Export your Sphinx conversations as Markdown files to share with colleagues or document your analysis process.
Exporting a Chat
- Click the export icon (↓) in the chat panel header
- Choose a location and filename
- The conversation is saved as a formatted Markdown file
What’s Included
The exported Markdown contains:
- Chat label and timestamp
- All user messages
- Sphinx’s responses and reasoning
- Code cells (original and modified versions)
- Cell execution information
- Tool usage (web searches, file reads, etc.)
Cell outputs (like plots and DataFrames) are not included in the export. The focus is on the conversation flow and code changes.
Multi-Tasking
Sphinx supports working with multiple notebooks simultaneously. Each notebook maintains its own:
- Conversation history
- Kernel context
- Checkpoint state
How Multi-Tasking Works
- Open multiple notebooks in different tabs
- Each notebook has independent Sphinx conversations
- Switch between notebooks freely (unless locked to a specific one)
- Conversations continue where you left off when you return
Running Multiple Conversations
While Sphinx can only actively generate in one notebook at a time, you can:
- Start a task in Notebook A
- Switch to Notebook B and start a different task
- Return to Notebook A to continue or review
Settings Reference
All Sphinx settings can be configured in your editor’s settings (Cmd+, / Ctrl+,):
| Setting | Default | Description |
|---|
sphinx.autosave | true | Auto-save notebook after each conversation step |
sphinx.collapse-exploratory-cells | false | Auto-collapse intermediate exploration cells |
sphinx.enable-checkpoints | true | Save notebook state before conversations |
sphinx.show-edit-cell-wand | true | Show the edit wand on notebook cells |
sphinx.memory-read | true | Use learned insights to inform actions |
sphinx.memory-write | true | Learn new insights about your data |
sphinx.web-search | true | Allow web searches for information |
sphinx.require-web-search-approval | false | Require approval for web searches |
sphinx.file-search | true | Allow searching/reading workspace files |
sphinx.package-installation | true | Allow installing new packages |
sphinx.enable-runtime-interrupts | true | Auto-interrupt long-running cells |
