notebook-ai-extension/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

opencode_bridge is a JupyterLab extension that acts as a thin bridge between the JupyterLab UI and a locally-running OpenCode Serve process (an AI coding assistant). The architecture, UI flow, and reference TypeScript skeletons are documented in design.md — read it before changing the interaction model. The high-level shape is: floating toolbar injected into each CodeCell → context provider (cell source, error traceback, neighbours) → REST/SSE call to the Jupyter server extension → server extension forwards to OpenCode Serve over local socket/HTTP.

This is a dual-package extension (one Python package + one NPM package) scaffolded from the JupyterLab extension-template v4.6.2 via Copier (see .copier-answers.yml). Do not hand-edit files marked "NEVER EDIT MANUALLY" in that file.

Repository layout

Path	Purpose
src/	TypeScript frontend (JupyterLab plugin lives in src/index.ts, REST helper in src/request.ts)
opencode_bridge/	Python server extension package; routes registered in opencode_bridge/routes.py
schema/plugin.json	Frontend settings schema (currently empty properties: {})
style/	CSS entry points; base.css is empty, only index.css imports it
lib/	Build output of src/ (gitignored)
opencode_bridge/labextension/	Build output of the full labextension bundle (gitignored)
ui-tests/	Playwright + Galata integration tests (separate package.json with its own jlpm install)
jupyter-config/server-config/opencode_bridge.json	Auto-enables the server extension on install
design.md	Architecture, UI flow, and reference TS skeletons — source of truth for the design
.github/workflows/build.yml	CI: uv build with Tsinghua PyPI mirror, then Gitea release + Bark notify

The Python and JS package share the name opencode_bridge but live in different namespaces: the server extension is mounted at the URL prefix opencode-bridge/... (note the hyphen), while the Python/JS module name uses the underscore. Frontend → backend calls must hit <baseUrl>/opencode-bridge/<endpoint>.

Common commands

All JS commands go through jlpm (JupyterLab's pinned yarn). The yarn setup uses pnpm as the node linker (see .yarnrc.yml) and disables enableScripts; do not run plain npm install on the root.

Install / dev setup

python -m venv .venv && source .venv/bin/activate
pip install --editable ".[dev,test]"
jupyter-builder develop . --overwrite          # link frontend
jupyter server extension enable opencode_bridge   # server ext must be enabled manually in dev
jlpm install

Build

jlpm build           # tsc + jupyter-builder (dev), fast iteration
jlpm build:prod      # full clean prod build for distribution
jlpm watch           # tsc -w + jupyter-builder watch in parallel

Tests

jlpm test            # jest unit tests (src/__tests__/*) with coverage
pytest               # python tests (opencode_bridge/tests/*) — uses pytest-jupyter
# Integration (Playwright + Galata):
(cd ui-tests && jlpm install && jlpm playwright install)   # once
jlpm build:prod                                                    # required before UI tests
(cd ui-tests && jlpm playwright test)                              # run
(cd ui-tests && jlpm playwright test -u)                           # update snapshots

Jest config (jest.config.js) extends @jupyterlab/testutils/lib/jest-config; tests match src/.*/.*.spec.ts[x]?$. ESLint ignores **/*.js, **/*.d.ts, tests, __tests__, and ui-tests — TS files outside ui-tests are the only ones linted.

Lint / format

jlpm lint           # stylelint + prettier + eslint (--fix variants)
jlpm lint:check     # CI variant, no --fix

Prettier is configured for single quotes, no trailing commas, no arrow parens (see package.json overrides). Stylelint enforces kebab-case class selectors.

Release

RELEASE.md documents the manual flow (hatch version, jlpm clean:all, python -m build). The CI workflow auto-builds and creates a Gitea release on v* tags, then pushes a Bark notification (.github/scripts/bark-notify.sh) — Bark failures are non-fatal by design.

Conventions specific to this repo

• Server extension is enabled in two places: jupyter-config/server-config/opencode_bridge.json (auto, on pip install) and must be enabled manually in dev mode. The pytest config (conftest.py) re-enables it via the jp_server_config fixture.
• URL prefix vs. package name: REST endpoints are mounted under opencode-bridge/ (hyphen), even though the Python and JS packages are named opencode_bridge (underscore). src/request.ts hardcodes the hyphenated prefix; keep them in sync if you add endpoints.
• Endpoint handlers must decorate every verb method with @tornado.web.authenticated (see opencode_bridge/routes.py); the existing HelloRouteHandler only implements get — if you add POST/PATCH/PUT/DELETE, decorate each one.
• Settings: schema/plugin.json currently has no properties; the frontend loads it via ISettingRegistry in src/index.ts. When you add a setting, update schema/plugin.json, the settingRegistry.load(...) consumer, and document defaults.
• Dev install of UI tests is a separate subproject: ui-tests/package.json is not part of the root workspace. Run jlpm install inside ui-tests/ once; do not move those deps to the root.
• Generated artefacts: opencode_bridge/_version.py is generated by hatch (gitignored) and opencode_bridge/labextension/ is generated by the labextension build (gitignored). If you see them missing locally, you haven't run jlpm build yet.
• PyPI mirror: pyproject.toml pins the Tsinghua mirror for uv/pip, and CI sets UV_DEFAULT_INDEX to the same. Other users on slow/non-China networks may need to override this.

Where to start when changing…

• Adding a new REST endpoint: add the handler in opencode_bridge/routes.py (with @tornado.web.authenticated on every verb), register the route under opencode-bridge/<name> in setup_route_handlers, then call it from the frontend via the requestAPI helper in src/request.ts.
• Changing the cell UI / toolbar / inline prompt box: design.md has working reference skeletons for src/context_provider.ts and src/components/cell_toolbar.ts — implement them; do not invent a new interaction model without updating the design doc.
• Adding a JupyterLab setting: schema/plugin.json + consume via ISettingRegistry in src/index.ts.
• Packaging / release: RELEASE.md + .github/workflows/build.yml; remember CI uses Gitea, not GitHub Releases.