Metadata-Version: 2.4
Name: jupyter-claude-plugin
Version: 0.1.0a1
Summary: Collaborate with Claude on Jupyter notebook code and documentation
Project-URL: Homepage, https://github.com/DCKartasoft/Jupyter-Claude_Plugin
Project-URL: Documentation, https://github.com/DCKartasoft/Jupyter-Claude_Plugin/blob/main/docs/USER_GUIDE.md
Project-URL: Repository, https://github.com/DCKartasoft/Jupyter-Claude_Plugin
Project-URL: Issues, https://github.com/DCKartasoft/Jupyter-Claude_Plugin/issues
Project-URL: Changelog, https://github.com/DCKartasoft/Jupyter-Claude_Plugin/blob/main/CHANGELOG.md
Author-email: David Cleminson <david.cleminson@kartasoft.com>
License: BSD 3-Clause License
        
        Copyright (c) 2026, David Cleminson
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: ai,anthropic,bedrock,claude,jupyter,jupyterlab,jupyterlab-extension,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: claude-agent-sdk>=0.1
Requires-Dist: jupyter-collaboration>=2.0
Requires-Dist: jupyter-mcp-server>=1.0
Requires-Dist: jupyter-server<3,>=2.4.0
Provides-Extra: dev
Requires-Dist: jupyter-builder>=1.0.0; extra == 'dev'
Requires-Dist: jupyterlab>=4; extra == 'dev'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-jupyter[server]>=0.6.0; extra == 'test'
Description-Content-Type: text/markdown

# Jupyter Claude Plugin

A JupyterLab extension enabling collaborative development between users and Claude. Chat about your notebook, generate cells from prompts, explain and document existing code, and fix errors — all within JupyterLab.

> **Status:** early development, scaffold phase complete. See [docs/PLAN.md](docs/PLAN.md) for the implementation plan and [docs/DECISIONS.md](docs/DECISIONS.md) for the decision log.

## Features (v1)

- **Chat about the notebook** — ask Claude to analyze, summarize, or answer questions about your entire notebook
- **Generate a cell** — describe what you want; choose cell type (code/markdown/raw); Claude generates and inserts it
- **Explain a cell** — Claude documents an existing cell with a markdown explanation
- **Fix last error** — Claude sees the error from your last cell run and offers a corrected version
- **Runtime tier selector** — switch between opus/sonnet/haiku in the chat panel for quality/speed tradeoffs (Bedrock only)
- **MCP server management** — enable/disable individual MCP servers from `~/.claude.json` per session via dialog command (defaults to Jupyter only for faster startup)
- **Notebook toolbar buttons** — all five commands as icons in toolbar: Open Chat, Generate cell, Explain cell, Fix last error, and MCP server selector
- **Visual feedback** — animated "Claude is thinking…" spinner while processing; disabled tier selector during requests

## Requirements

- JupyterLab >= 4.0.0
- Node >= 20
- Python >= 3.10 (this project targets 3.13)
- `uv` package manager (via Homebrew: `brew install uv`)

## Install (from PyPI, recommended)

```bash
pip install --pre jupyter-claude-plugin
```

`--pre` is required for alpha releases. Runtime dependencies (`claude-agent-sdk`, `jupyter-mcp-server`, `jupyter-collaboration`) are pulled in automatically. See [docs/USER_GUIDE.md](docs/USER_GUIDE.md) for backend configuration and usage.

## Development install (from source)

```bash
cd /path/to/Jupyter-Claude_Plugin
uv venv
source .venv/bin/activate

jlpm install
uv pip install -e ".[dev,test]"
jlpm build
jupyter labextension develop . --overwrite
jupyter server extension enable jupyter_claude

jupyter lab
```

## Global MCP servers (user scope, one-time)

```bash
claude mcp add --scope user filesystem -- npx -y @modelcontextprotocol/server-filesystem $HOME
claude mcp add --scope user memory -- npx -y @modelcontextprotocol/server-memory
claude mcp add --scope user sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking
claude mcp add --scope user fetch -- uvx mcp-server-fetch
claude mcp add --scope user git -- uvx mcp-server-git
claude mcp add --scope user jupyter --transport http http://localhost:8888/mcp
```

## Backend

The extension supports two Claude backends. Pick one in the JupyterLab Settings Editor (or via `jupyter_server_config.py`) — everything else is derived from that choice.

### Anthropic direct

Set `ANTHROPIC_API_KEY` in the environment before launching Jupyter. The extension will use the `model` trait (default `claude-opus-4-8`).

### AWS Bedrock via shared SSO

Configuration lives in the extension traits (not shell env — the extension writes the right vars into the Claude Agent SDK subprocess itself):

- `backend = "bedrock"`
- `aws_region = "us-east-1"` (or your region)
- `aws_profile = "<your profile>"` — a named profile from `~/.aws/config` (enables shared AWS SSO; profile and region are forwarded to the SDK subprocess)
- `default_opus_model`, `default_sonnet_model`, `default_haiku_model` — inference-profile model IDs (defaults: `us.anthropic.claude-opus-4-7`, `us.anthropic.claude-sonnet-4-6`, `us.anthropic.claude-haiku-4-5-20251001-v1:0`)

Refresh your SSO session and start Jupyter with `aws-vault` so the subprocess inherits temporary STS credentials without leaking them to disk:

```bash
aws sso login --profile <your profile>              # once per session
aws-vault exec <your profile> -- jupyter lab
```

If you prefer not to use `aws-vault`, `AWS_PROFILE=<name> AWS_REGION=<region> jupyter lab` also works — the extension forwards those to the SDK.

See [docs/PLAN.md](docs/PLAN.md) for design details.

## Architecture

```
JupyterLab (browser)
  └─ Frontend extension (TS/React)
       ├─ Right-side chat panel
       ├─ Cell toolbar buttons
       └─ Context-menu items
                          ↓ WebSocket
                  Server extension (Python)
                    └─ ClaudeSDKClient
                         ├─ Anthropic API | AWS Bedrock
                         └─ Jupyter MCP server (same process)
```

Claude reads/writes/executes cells via MCP tools; the extension provides no custom cell tools.

## Troubleshoot

If the frontend extension is not working, check that the server extension is enabled:

```bash
jupyter server extension list
```

If the server extension is installed and enabled but the frontend is not showing up, check that the frontend extension is installed:

```bash
jupyter labextension list
```

## Documentation

- **[docs/USER_GUIDE.md](docs/USER_GUIDE.md) — install & operation guide (start here)**
- [docs/PLAN.md](docs/PLAN.md) — step-by-step implementation roadmap
- [docs/DECISIONS.md](docs/DECISIONS.md) — decision log and rationale
- [docs/Architecture.md](docs/Architecture.md) — component diagram and data flow
- [CHANGELOG.md](CHANGELOG.md) — human-readable milestone log

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

_This README is maintained by an automated doc-keeper — it re-writes from [docs/DECISIONS.md](docs/DECISIONS.md) every 10 minutes._
