jupyter-cc 0.1.0

Jupyter magic for Claude Code — %cc brings agentic AI into your notebook cells

jupyter-cc

Jupyter magic for Claude Code -- %cc brings agentic AI into your notebook cells.

jupyter-cc integrates Claude Code directly into Jupyter notebooks as IPython magic commands. Instead of switching between a sidebar or terminal and your notebook, you stay in the notebook: type %cc with a prompt, and Claude reads your variables, executes tools, and creates new code cells for you to review and run.

Built on the Claude Agent SDK with an in-process MCP server, jupyter-cc gives Claude the same agentic capabilities it has in Claude Code CLI -- file editing, shell commands, web search -- plus the ability to create notebook cells.

Example Session

# Cell 1: Load the extension
%load_ext jupyter_cc

# Cell 2: Ask Claude to analyze data
%cc Load the sales.csv file and show summary statistics

# Cell 3: Claude creates a code cell for you to review and run
# ... (auto-generated by Claude)

# Cell 4: Follow up in the same conversation
%cc Now plot monthly revenue trends with a 3-month moving average

Installation

Prerequisites

1. Python 3.13+ -- check with python --version
2. Claude Code authentication -- one of:
   • Claude Code CLI installed (claude --version) -- install from Claude Code docs
   • OR Claude Pro/Max subscription with API access
3. Jupyter (for notebook usage) or IPython (for terminal usage):

   pip install jupyter
   # or
   pip install ipython
   

Install

Install directly from GitHub:

pip install git+https://github.com/vinceyyy/jupyter-cc.git

With uv:

uv pip install git+https://github.com/vinceyyy/jupyter-cc.git

Quick Start

After installation:

# In a Jupyter notebook or IPython session:
%load_ext jupyter_cc
%cc Hello! What can you help me with?

Uninstall

pip uninstall jupyter-cc

Development (for contributors)

If you want to contribute to jupyter-cc, clone the repo and install in development mode:

git clone https://github.com/vinceyyy/jupyter-cc.git
cd jupyter-cc
uv sync

Usage

%load_ext jupyter_cc

Magic Commands

Command	Alias	Description
%cc <prompt>		Continue conversation with Claude (one-line)
%%cc		Continue conversation with Claude (multi-line)
%cc_new <prompt>	%ccn	Start a fresh conversation (no history)
%cc_cur <prompt>	%ccc	Like %cc, but replaces the prompt cell in-place

Use %%cc (cell magic with double %) when your prompt spans multiple lines or ends with ? (to avoid IPython's help system).

Options

Option	Description
--model <name>	Model to use (default: sonnet)
--max-cells <num>	Max cells Claude can create per turn (default: 3)
--import <file>	Include a file in the initial conversation context
--add-dir <dir>	Add a directory to Claude's accessible paths
--mcp-config <file>	Path to .mcp.json with additional MCP server configs
--cells-to-load <num>	Number of recent cells to load into a new conversation
--clean	Replace prompt cells with Claude's code cells
--no-clean	Keep prompt cells (default)
--verbose, -v	Show detailed tool call arguments
--help, -h	Show usage information

Skills and Context

The Claude Agent SDK automatically reads configuration from your project and user directories. No extra setup is needed -- just place files in the right locations.

Project-level (checked into your repo):

• .claude/CLAUDE.md -- project instructions, coding conventions, architecture notes
• .claude/settings.local.json -- tool permissions (auto-created on first load)
• .claude/skills/ -- project-specific skill files (*.md)

User-level (your personal config):

• ~/.claude/CLAUDE.md -- global instructions applied to all projects
• ~/.claude/skills/ -- personal skills available everywhere

To add a skill, create a Markdown file in .claude/skills/ or ~/.claude/skills/. To customize Claude's behavior for a project, edit .claude/CLAUDE.md in your project root.

For a detailed breakdown of what Claude sees when you run %cc -- variables, cell history, images, system prompt, and more -- see What CC Sees.

Project Structure

src/jupyter_cc/
├── __init__.py      # Extension entry point, permissions setup
├── magics.py        # %cc, %cc_new, %cc_cur magic commands, MCP server
├── client.py        # SDK client lifecycle, streaming, interrupt handling
├── config.py        # CLI options (--model, --add-dir, --import, etc.)
├── prompt.py        # System prompt construction
├── integration.py   # Cell creation, queue management, env detection
├── history.py       # IPython cell history tracking
├── variables.py     # Session variable change detection
├── capture.py       # Image extraction from cell outputs
├── watcher.py       # "Run All" detection via timing heuristics
├── constants.py     # Help text, tool names
└── py.typed         # PEP 561 type marker

Development

uv sync                        # Install dependencies
uv run ruff check src/ --fix   # Lint (auto-fix)
uv run ruff format src/        # Format
uv run pyright src/            # Type check
uv run pytest                  # Run tests
uv build                       # Build wheel/sdist

Acknowledgements

jupyter-cc is adapted from:

• notellm by Bryan Daniels
• claude-code-jupyter-staging by Anthropic

Released under the MIT License. See LICENSE.