jupyter-claude-plugin 0.1.0a1__tar.gz

jupyter_claude_plugin-0.1.0a1/.copier-answers.yml

@@ -0,0 +1,16 @@
+# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
+_commit: v4.6.2
+_src_path: https://github.com/jupyterlab/extension-template
+advanced: false
+author_email: david.cleminson@kartasoft.com
+author_name: David Cleminson
+has_ai_rules: false
+has_binder: false
+has_settings: true
+kind: frontend-and-server
+labextension_name: '@dckartasoft/jupyter-claude'
+project_short_description: Collaborate with Claude on Jupyter notebook code and documentation
+python_name: jupyter_claude
+repository: https://github.com/DCKartasoft/Jupyter-Claude_Plugin
+test: true
+

jupyter_claude_plugin-0.1.0a1/.gitignore

@@ -0,0 +1,137 @@
+*.bundle.*
+lib/
+node_modules/
+*.log
+.eslintcache
+.stylelintcache
+*.egg-info/
+.ipynb_checkpoints
+*.tsbuildinfo
+jupyter_claude/labextension
+# Version file is handled by hatchling
+jupyter_claude/_version.py
+
+# Integration tests
+ui-tests/test-results/
+ui-tests/playwright-report/
+
+# Created by https://www.gitignore.io/api/python
+# Edit at https://www.gitignore.io/?templates=python
+
+### Python ###
+# Virtual environments
+.venv
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage/
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# End of https://www.gitignore.io/api/python
+
+# OSX files
+.DS_Store
+
+# Yarn cache
+.yarn/
+
+# Claude Code
+.claude/scheduled_tasks.lock
+.claude/settings.local.json
+
+# Jupyter runtime state
+.jupyter/
+.jupyter_ystore.db
+Untitled*.ipynb

jupyter_claude_plugin-0.1.0a1/.prettierignore

@@ -0,0 +1,8 @@
+node_modules
+**/node_modules
+**/lib
+**/package.json
+!/package.json
+jupyter_claude
+eslint.config.mjs
+.venv

jupyter_claude_plugin-0.1.0a1/.yarnrc.yml

@@ -0,0 +1,2 @@
+nodeLinker: node-modules
+enableScripts: false

jupyter_claude_plugin-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+<!-- <START NEW CHANGELOG ENTRY> -->
+
+## Unreleased
+
+- PyPI publish prep — package renamed `jupyter-claude-plugin`, version 0.1.0a1: renamed distribution to `jupyter-claude-plugin` (internal Python package stays `jupyter_claude`); PEP 440 pre-release tag `0.1.0a1` prevents auto-install; added `claude-agent-sdk`, `jupyter-mcp-server`, `jupyter-collaboration` to `[project].dependencies`; moved project URLs from `dynamic` to explicit `[project.urls]` block; fixed wheel discovery; validated wheel installation (`jupyter_claude_plugin-0.1.0a1-py3-none-any.whl`); updated install instructions (prefer `pip install --pre jupyter-claude-plugin` over source).
+- SageMaker deployment section added to `docs/USER_GUIDE.md`: covers JupyterLab 4 environment setup, required IAM permissions (bedrock InvokeModel + ResponseStream + ListInferenceProfiles + GetInferenceProfile), lifecycle config/terminal install script (Node 20 + Claude Code CLI + deps + extension), and SageMaker-specific gotchas (leave aws_profile empty for IAM role, ephemeral extension links in Studio, region-specific model IDs, no egress rules needed).
+- User guide added at `docs/USER_GUIDE.md`: comprehensive install & operation manual covering requirements, dev setup, both backend paths (Anthropic + Bedrock SSO), launching, all five v1 commands, per-tier model reference, troubleshooting (including page_config.json disable gotcha), and uninstall.
+- MCP server enumeration + runtime selector: `jupyter_claude/mcp_discovery.py` reads `~/.claude.json`, new `enabled_mcp_servers` trait with GET/POST REST endpoints at `/jupyter-claude/mcp-servers`, frontend dialog to enable/disable individual servers (default: `["jupyter"]`), MCP client restarts with fresh filter on selection change.
+- Runtime model selector in chat panel: dropdown to switch tier (opus/sonnet/haiku) per conversation without editing config; disabled for Anthropic direct or during requests; tier selection resets conversation history.
+- `main_model_tier` trait for speed/quality tradeoff: Sonnet 4.6 is default; Opus for max quality, Haiku for max speed; resolved model sent back in `ready` frame.
+- Panel spinner and command-triggered busy state: animated "Claude is thinking…" indicator while processing; command flows now set busy state alongside panel updates.
+- Full command set on notebook toolbar: all four Claude commands (Open Chat, Generate, Explain, Fix) plus MCP Servers selector now appear as icon-only toolbar buttons (ranks 60–63) with tooltips; cell toolbar keeps just Explain.
+- Custom `claudeIcon` (blue SVG spark): new `src/icons.ts` exports an inline LabIcon showing a stylised blue 4-point spark (`#4361ee`), replacing generic `codeIcon` on sidebar tab and Open Chat button.
+- Command dialogs use JupyterLab InputDialog instead of `window.prompt()` (browser-blocked); fixed last-error tracking by notebook ID consistency.
+- Cell-type dropdown for Generate command: select code/markdown/raw before description; prompts adapt by type and respect no-execute for markdown/raw cells.
+- `page_config.json` cleaned: removed stale disabled/locked extension entries that silently blocked activation.
+- Labextension linked as symlink via `jupyter labextension develop . --overwrite` in dev workflow; clears stale bundled copies.
+- Bedrock config expanded: added `aws_profile` trait for shared AWS SSO, plus `default_opus_model`, `default_sonnet_model`, `default_haiku_model` traits for per-tier inference-profile IDs (defaults: `us.anthropic.claude-opus-4-7`, `us.anthropic.claude-sonnet-4-6`, `us.anthropic.claude-haiku-4-5-20251001-v1:0`).
+- Frontend cell-write path: Claude calls `mcp__jupyter__*` tools (insert_cell, insert_execute_code_cell) directly; frontend does not parse code blocks. Cleaner separation of concerns.
+- React 18 pinned to `^18.2.0` for JupyterLab 4 type compatibility; `tsconfig.json` moduleResolution set to `bundler`.
+- Frontend built: React chat panel with message list, WebSocket client with auto-reconnect, five v1 commands (chat, generate, explain, fix, mcp-servers), cell toolbar buttons and context menu entries.
+- Server extension built: `ClaudeExtensionApp` with configurable backend/model/region traits, `ClaudeSDKClient` per WS connection, chat handler at `/jupyter-claude/chat`.
+- JupyterLab extension scaffold generated via copier (frontend-and-server, package `@dckartasoft/jupyter-claude`, Python `jupyter_claude`).
+- Fixed malformed `labextension_name` (`myextension@dc-ks/jupyter-claude` → `@dckartasoft/jupyter-claude`) across all config and code files.
+- Root `CHANGELOG.md` is now the single changelog; `docs/CHANGELOG.md` removed.
+- Initial commit landed (root `6e4db50`): plan, decisions, doc-keeper cron config, uv boilerplate, stub.
+- Haiku doc-keeper cron: every 10 minutes reads `docs/DECISIONS.md` and syncs `PLAN.md`, `README.md`, `CHANGELOG.md`, `Architecture.md`.
+- Corrected MCP server registration: `fetch` and `git` are Python packages; use `uvx` not `npx`.
+- Plan location: dual (`~/.claude/plans/...` internal + `docs/PLAN.md` versioned).
+- Dev environment locked to Homebrew + `uv` (no pipx); `uvx` replaces pipx for one-shot tools.
+- Global MCP servers registered at user scope: filesystem, memory, sequential-thinking, fetch (Python), git (Python), jupyter (HTTP).
+- Support both Anthropic direct and AWS Bedrock backends; env-var driven, inference-profile model IDs for Bedrock.
+- MCP on both sides: plugin backend acts as MCP client; connects to `jupyter-mcp-server` for cell R/W/execute. No hand-rolled cell tools.
+- Target: JupyterLab frontend-and-server extension (not classic + magics); richest UX with sidebar chat, cell toolbar, context menus.
+- Four v1 interactions: chat about notebook, generate cell, explain/document cell, fix last error.
+- Project initialized (2026-07-07).
+
+_This changelog is maintained by an automated doc-keeper — it re-writes from [docs/DECISIONS.md](docs/DECISIONS.md) every 10 minutes._
+
+<!-- <END NEW CHANGELOG ENTRY> -->

jupyter_claude_plugin-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing
+
+## Development install
+
+Note: You will need Node.js to build the extension package.
+You may install it from [nodejs.org](https://nodejs.org/en/download). We
+recommend using the latest LTS version of Node.js.
+
+The `jlpm` command is JupyterLab's pinned version of
+[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
+`yarn` or `npm` in lieu of `jlpm` below.
+
+```bash
+# Clone the repo to your local environment
+# Change directory to the jupyter_claude directory
+
+# Set up a virtual environment and install package in development mode
+python -m venv .venv
+source .venv/bin/activate
+pip install --editable ".[dev,test]"
+
+# Link your development version of the extension with JupyterLab
+jupyter-builder develop . --overwrite
+# Server extension must be manually installed in develop mode
+jupyter server extension enable jupyter_claude
+
+# Rebuild extension Typescript source after making changes
+# IMPORTANT: Unlike the steps above which are performed only once, do this step
+# every time you make a change.
+jlpm build
+```
+
+You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.
+
+```bash
+# Watch the source directory in one terminal, automatically rebuilding when needed
+jlpm watch
+# Run JupyterLab in another terminal
+jupyter lab
+```
+
+With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).
+
+By default, the `jlpm build` command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:
+
+```bash
+jupyter lab build --minimize=False
+```
+
+## Development uninstall
+
+```bash
+# Server extension must be manually disabled in develop mode
+jupyter server extension disable jupyter_claude
+pip uninstall jupyter_claude
+```
+
+In development mode, you will also need to remove the symlink created by `jupyter-builder develop`
+command. To find its location, you can run `jupyter labextension list` to figure out where the `labextensions`
+folder is located. Then you can remove the symlink named `@dckartasoft/jupyter-claude` within that folder.
+
+## Testing the extension
+
+### Server tests
+
+This extension is using [Pytest](https://docs.pytest.org/) for Python code testing.
+
+Install test dependencies (needed only once):
+
+```sh
+pip install -e ".[test]"
+# Each time you install the Python package, you need to restore the front-end extension link
+jupyter-builder develop . --overwrite
+```
+
+To execute them, run:
+
+```sh
+pytest -vv -r ap --cov jupyter_claude
+```
+
+#### Frontend tests
+
+This extension is using [Jest](https://jestjs.io/) for JavaScript code testing.
+
+To execute them, execute:
+
+```sh
+jlpm
+jlpm test
+```
+
+### Integration tests
+
+This extension uses [Playwright](https://playwright.dev/docs/intro) for the integration tests (aka user level tests).
+More precisely, the JupyterLab helper [Galata](https://github.com/jupyterlab/jupyterlab/tree/master/galata) is used to handle testing the extension in JupyterLab.
+
+More information is provided within the [ui-tests](./ui-tests/README.md) README.
+
+## Packaging the extension
+
+See [RELEASE](RELEASE.md)

jupyter_claude_plugin-0.1.0a1/LICENSE

@@ -0,0 +1,29 @@
+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.

jupyter_claude_plugin-0.1.0a1/PKG-INFO

@@ -0,0 +1,207 @@
+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._

jupyter_claude_plugin-0.1.0a1/README.md

@@ -0,0 +1,131 @@
+# 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._