User Guide#
Jupyter AI connects models, agents, and workflows to notebooks. Start from what you want to accomplish, then choose the way of working that fits your setup. All of them share the same building blocks, so you can combine them.
What do you want to accomplish?#
Goal |
Where to start |
|---|---|
Debug a notebook |
Ask an agent to run the notebook, read the errors, and fix the code: a terminal agent, the agent chat, or Jupyternaut in the browser. In the agent chat, you can also attach the failing cells to your message. |
Edit and run notebooks with an agent |
Terminal agents edit notebook files and run cells through JupyterLab. Agents in the agent chat and Jupyternaut in the browser work in the open notebook. |
Create a domain workflow |
Write instructions and skills for your field, give agents your own tools, or build a custom AI persona. |
Use a local or private model |
Point Jupyternaut in the browser or the Jupyternaut persona at Ollama, vLLM, or another OpenAI-compatible server. Agents such as OpenCode and Goose can also use local models through their own configuration. |
Connect an existing agent |
Register the Jupyter MCP server with your terminal agent, or install the agent for the agent chat. |
Add specialized tools |
Add MCP servers to the agent chat, or write tools that every agent can call. |
Ways to use Jupyter AI#
Run Claude Code, Codex, or another coding agent in a terminal, and connect it to JupyterLab with MCP.
Chat with agents in a JupyterLab side panel, with permission prompts and shared chats.
An assistant that runs in the browser tab with your own API key, also in JupyterLite.
Compare the options#
Terminal coding agents |
Agent chat |
In the browser |
|
|---|---|---|---|
You talk to the agent in |
The agent’s own interface: a terminal, a desktop app, or an editor |
A chat panel in JupyterLab |
A chat panel in JupyterLab, Jupyter Notebook, or JupyterLite |
The agent runs |
In its own process, started by you |
In a process started by the Jupyter server |
In the browser tab |
Agents |
Any agent that supports MCP |
Agents that support ACP: Claude, Codex, GitHub Copilot, Gemini, Goose, Kiro, Mistral Vibe, OpenCode, and more |
Jupyternaut, with models from Anthropic, Google, Mistral, OpenAI, OpenRouter, or any OpenAI-compatible server |
Model access |
The agent’s own sign-in or API key |
The agent’s own sign-in or API key |
An API key, or a local model server |
Acts on JupyterLab through |
The Jupyter MCP server |
The Jupyter MCP server |
JupyterLab commands, directly |
Needs a Jupyter server |
Yes |
Yes |
No: also runs in JupyterLite |
Install |
|
|
|
Which one should I use?#
You already use a coding agent such as Claude Code or Codex: start with Terminal coding agents. You keep your agent as it is, and it learns to work with JupyterLab.
You want a chat panel inside JupyterLab, to try several agents or to share chats with other people: use the agent chat.
You cannot install agents on the server, deploy JupyterLite, or want the smallest setup with an API key: use Jupyternaut in the browser.
You want to prompt a model from a notebook cell: use the magic commands.
The options are not exclusive. The jupyter-ai package includes
jupyter-ai-core, so it runs the same Jupyter MCP server that terminal agents
use, and you can keep a coding agent in a terminal next to the chat panel. See
How it fits together for the building blocks they share.
More projects#
Many more AI extensions for Jupyter exist, from other teams and companies. Other projects points to a community-maintained list.