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#

🖥️ Terminal coding agents

Run Claude Code, Codex, or another coding agent in a terminal, and connect it to JupyterLab with MCP.

Terminal coding agents
💬 Agent chat

Chat with agents in a JupyterLab side panel, with permission prompts and shared chats.

Agent chat
🌐 In the browser

An assistant that runs in the browser tab with your own API key, also in JupyterLite.

Jupyternaut in the browser

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

pip install jupyter-ai-core

pip install jupyter-ai

pip install jupyter-ai-lite

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.