Hypernote
- JupyterLab-first - Hypernote is a thin execution control plane for a Hypernote-enabled JupyterLab server.
- One notebook truth - notebook edits, execution, and late-open JupyterLab views all operate on the same logical document.
- Agent-first surface - the Python SDK is primary, and the CLI is a thin shell over it.
- Ephemeral control plane - Jupyter owns durable
.ipynbcontents and outputs; Hypernote owns in-memory runtimes, jobs, and attribution. - Temporary collaboration journal -
setup servekeeps Jupyter RTC updates in server-local temp storage, not repo-root databases.
What it ships
- notebook-first SDK in
src/hypernote/sdk.py - agent-first CLI in
src/hypernote/cli/main.py - Jupyter server extension for execution and runtime control
- subshell-routed execute, interrupt, and restart so JupyterLab stays usable while Hypernote is running cells
- notebook-scoped runtime lifecycle with attach, detach, recovery, and stop
- job polling and
input()round-trips for agent automation without requiring an open Lab tab - live-server and browser regression coverage for shared-document behavior
Quick start
uv sync
uv run hypernote setup doctor
# If no Hypernote API is reachable, start the server from this repo.
# Omit --no-browser when you want setup to open JupyterLab immediately.
uv run hypernote setup serve --no-browser > tmp/hypernote-serve.log 2>&1 &
for _ in 1 2 3 4 5 6 7 8 9 10; do
uv run hypernote setup doctor | grep -q '"hypernote_api"[[:space:]]*:[[:space:]]*"ok"' && break
sleep 0.5
done
uv run hypernote setup doctor
notebook_path="tmp/demo-$(date +%Y%m%d-%H%M%S).ipynb"
uv run hypernote create "$notebook_path" --empty --brief
uv run hypernote ix "$notebook_path" -s 'value = 20 + 22; print(value)' --brief
uv run hypernote status "$notebook_path" --brief
Use the notebook path you actually want. The tmp/demo-... path above is only a
disposable example that avoids overwriting an existing notebook.
--brief keeps the cell's output_preview while omitting hints, snapshot
tokens, and bulky raw output payloads.
For another repo's environment, install Hypernote there (uv add hypernote --dev) and run
setup doctor / setup serve from that repo so kernels and notebook paths line up.
Install
The default install includes the JupyterLab integration stack Hypernote needs: JupyterLab, shared-document support, server-side notebook execution, and the Hypernote server extension.
Hypernote supports Python 3.11 through 3.13. setup serve is intentionally
local-only: it accepts loopback hosts such as 127.0.0.1, localhost, and
::1, and rejects LAN or public bind addresses. Jupyter generates a local
authentication token; subsequent Hypernote CLI commands discover it
automatically when --server points at that server.
Use hypernote[dev] only for local development and CI tooling.
Examples:
uv sync
uv sync --extra dev
Mental model
Jupyter owns:
- notebook persistence
- shared YDoc document state
- temporary collaboration journal state for live RTC updates
- kernel and session primitives
- notebook rendering in JupyterLab
Hypernote owns:
- runtime lifecycle around a notebook
- job coordination and stdin round-trips
- actor attribution
- SDK, CLI, and thin REST handlers
Contributor discipline
- shared behavior should have one owner, usually the SDK for agent-facing observation rules
- command and payload variants should preserve one contract unless a difference is explicit and documented
- adapters should normalize valid upstream shape differences at the boundary
- tests should cover invariants across variants, not only the main workflow
Documentation
Operator docs:
Contributor and advanced behavior docs:
Agents that only need to create, run, recover, or open notebooks can stop after the operator docs.
Verification
For local development and CI, install the dev tier first:
uv sync --extra dev
uv run ruff check src/hypernote tests
uv run python -m pytest -q
Metadata
Release files for hypernote 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hypernote-0.6.0.tar.gz | 215.8 kB | Without provenance | Details for hypernote-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hypernote-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for hypernote-0.6.0-py3-none-any.whl |
Total release size: 274.8 kB
Release files / hypernote-0.6.0.tar.gz
| Download URL | hypernote-0.6.0.tar.gz |
|---|---|
| Size | 215.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
953a0896c6195af6270583fec2f6f3fde7e6b171cb571bf8e8ea4805d88c9380
|
|
BLAKE2b-256 checksum How to use checksums |
c03f4d68a0dcd42c6e41f614e0f4c01213ac789c99894e552669efbf57a52e71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / hypernote-0.6.0-py3-none-any.whl
| Download URL | hypernote-0.6.0-py3-none-any.whl |
|---|---|
| Size | 59.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0ac213d88abe4276f3ffa2bb93d24f550c920a8f4ddba189fdad1b6e77a9ca87
|
|
BLAKE2b-256 checksum How to use checksums |
f6ffe21f72cd36fd833f66db2f00a824b8ce2aef86996721d183043869405758
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for hypernote 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.