Metadata-Version: 2.4
Name: jupyter-cc
Version: 0.1.0
Summary: Jupyter magic for Claude Code — %cc brings agentic AI into your notebook cells
License-Expression: MIT
Requires-Dist: anyio>=4.12.1
Requires-Dist: claude-agent-sdk>=0.1.39
Requires-Dist: ipython>=9.10.0
Requires-Dist: ipywidgets>=8.1.8
Requires-Dist: rich>=13.0.0
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/vinceyyy/jupyter-cc
Project-URL: Repository, https://github.com/vinceyyy/jupyter-cc
Project-URL: Issues, https://github.com/vinceyyy/jupyter-cc/issues
Description-Content-Type: text/markdown

# 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

```python
# 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`
1. **Claude Code authentication** -- one of:
   - Claude Code CLI installed (`claude --version`) -- install from [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code/overview)
   - OR Claude Pro/Max subscription with API access
1. **Jupyter** (for notebook usage) or **IPython** (for terminal usage):
   ```bash
   pip install jupyter
   # or
   pip install ipython
   ```

### Install

Install directly from GitHub:

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

With uv:

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

### Quick Start

After installation:

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

### Uninstall

```bash
pip uninstall jupyter-cc
```

### Development (for contributors)

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

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

## Usage

```python
%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](docs/what-cc-sees.md).

## 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

```bash
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](https://github.com/prairie-guy/notellm) by Bryan Daniels
- [claude-code-jupyter-staging](https://pypi.org/project/claude-code-jupyter-staging/) by Anthropic

Released under the MIT License. See [LICENSE](LICENSE.txt).
