{"id":13406340,"url":"https://github.com/nteract/nteract","last_synced_at":"2026-07-16T02:01:03.378Z","repository":{"id":337961360,"uuid":"1155631492","full_name":"nteract/nteract","owner":"nteract","description":"We're back! Now firing notebooks out of a t-shirt gun.","archived":false,"fork":false,"pushed_at":"2026-07-14T05:36:22.000Z","size":42407,"stargazers_count":144,"open_issues_count":32,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-07-14T07:10:25.209Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nteract.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-11T18:18:05.000Z","updated_at":"2026-07-13T22:50:25.000Z","dependencies_parsed_at":"2026-06-20T18:06:54.579Z","dependency_job_id":null,"html_url":"https://github.com/nteract/nteract","commit_stats":null,"previous_names":["runtimed/runt","nteract/desktop","nteract/nteract"],"tags_count":684,"template":false,"template_full_name":null,"purl":"pkg:github/nteract/nteract","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nteract%2Fnteract","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nteract%2Fnteract/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nteract%2Fnteract/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nteract%2Fnteract/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nteract","download_url":"https://codeload.github.com/nteract/nteract/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nteract%2Fnteract/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35527286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-science","desktop-application","ipython","jupyter","jupyter-notebook","monorepo","notebook","nteract","react","react-components","repl","zeromq"],"created_at":"2024-07-30T19:02:27.665Z","updated_at":"2026-07-16T02:01:03.373Z","avatar_url":"https://github.com/nteract.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Notebook Environments","Tools","Notebook环境","react-components","data-science","JavaScript","Built on rehype","Runtimes/Frontends"],"sub_categories":[],"readme":"# nteract\n\nnteract is a local-first notebook environment where humans, kernels, and AI agents can work against the same live document. It ships as a native desktop app with instant startup, realtime sync across windows and programmatic clients, and managed local environments.\n\nBuilt on [jupyter-zmq-client](https://crates.io/crates/jupyter-zmq-client) and [jupyter-protocol](https://crates.io/crates/jupyter-protocol).\n\n## Install\n\nDownload the latest release from [GitHub Releases](https://github.com/nteract/nteract/releases).\n\nLinux x64 and macOS (Apple silicon or Intel) can install with one command —\nthe AppImage or signed .app bundle plus CLI/daemon and the per-user service\n(systemd or launchd) in one step:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.nteract.io | bash\n```\n\nmacOS users can equally drag the DMG from GitHub Releases. DEB/RPM/APT\ninstalls are not currently supported because `runtimed` is a per-user daemon\nmanaged by the app and CLI, not by system package-manager scripts.\n\nFor remote workstations (Outerbounds, JupyterHub) that offer compute to\nhosted notebooks, use the headless one-liner — see\n[Remote workstations](docs/runbooks/remote-workstation.md):\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.nteract.io | bash -s -- --headless\n```\n\nThe desktop app bundles everything — `runt` CLI and `runtimed` daemon.\n\nThe `runt` CLI and `runtimed` Python bindings ship with the app and stay up to date automatically. For nightly builds, use `runt-nightly` instead.\n\n## What's in here\n\n| Component | Description |\n|-----------|-------------|\n| `nteract` | Desktop notebook editor (Tauri + React) |\n| `runtimed` | Background daemon — environment pools, notebook sync, kernel execution |\n| `runt` | CLI for managing kernels, notebooks, and the daemon |\n| `runtimed` (Python) | Python bindings for the daemon (ships with the app) |\n\n## Runtime model\n\nnteract stores notebook content in an Automerge-backed document and keeps live kernel state in an explicit runtime state document. The daemon owns kernel processes, execution queues, output capture, and the write path for execution results.\n\nExecution requests name a synced `cell_id`; the daemon reads the cell source from the shared document, records queue and status changes in runtime state, and writes outputs through the same model. The desktop app, CLI, MCP server, and agent clients use that path, so programmatic control observes the same notebook state a human is editing.\n\n## MCP Server\n\nThe nteract MCP server connects AI assistants to Jupyter notebooks through the daemon. Agents can run code, read and write cells, manage dependencies, and collaborate with humans in real-time — watching the notebook update live in the desktop app while the agent works.\n\n### Install the Codex plugin\n\n```\ncodex plugin marketplace add nteract/agent-plugins\n```\n\nRestart Codex, then open the plugin directory, choose the nteract marketplace, and install `nteract`.\n\nThe distribution repository also includes a `nightly` plugin entry for pre-release builds.\n\nIf Codex still does not show notebook tools after restarting, refresh the marketplace and reinstall the selected plugin:\n\n```\ncodex plugin marketplace upgrade nteract-plugins\ncodex plugin remove nteract@nteract-plugins      # or nightly@nteract-plugins\ncodex plugin add nteract@nteract-plugins         # or nightly@nteract-plugins\ncodex mcp list\n```\n\nStart a new Codex session after reinstalling; running sessions do not hot-load newly installed MCP tools.\n\n### Install the Claude Code plugin\n\n```\n/plugin marketplace add nteract/agent-plugins\n/plugin install nteract@nteract\n```\n\nPin a specific version:\n\n```\n/plugin install nteract@nteract --ref v2.3.0\n```\n\nThe plugin ships the right `nteract-mcp` binary for your platform (macOS arm64/x64, Linux x64, Windows x64) — no separate install needed. `main` of `nteract/agent-plugins` always points at the latest stable release.\n\nFor pre-release builds (updated daily):\n\n```\n/plugin install nightly@nteract\n```\n\n### Install in Claude Desktop\n\nIf you use the nteract desktop app with Claude Desktop, there's a one-click install path. In the menu bar, choose **nteract → Install Extension for Claude...**\n\n![nteract menu showing 'Install Extension for Claude...'](https://img.runt.run/install-claude-extension.png)\n\nThe desktop app builds a `.mcpb` bundle at runtime (manifest, icons, `nteract-mcp` binary) and hands it to Claude Desktop, which prompts you to confirm the install. Requires the nteract desktop app; Claude Desktop picks up the bundle from there.\n\n## Usage\n\n```bash\n# Open a notebook\nrunt notebook path/to/notebook.ipynb\n\n# MCP server for notebook automation\nrunt mcp\n\n# Daemon management\nrunt daemon status\nrunt daemon logs -f\n```\n\nList open notebooks with kernel and environment info:\n\n```\n$ runt notebooks\n╭──────────────────────────────────────┬────────┬──────────────┬────────┬───────╮\n│ NOTEBOOK                             │ KERNEL │ ENV          │ STATUS │ PEERS │\n├──────────────────────────────────────┼────────┼──────────────┼────────┼───────┤\n│ ~/notebooks/blobstore.ipynb          │ python │ uv:inline    │ idle   │ 1     │\n│ d4c441d3-d862-4ab0-afe6-ff9145cc2f3d │ python │ uv:prewarmed │ idle   │ 1     │\n╰──────────────────────────────────────┴────────┴──────────────┴────────┴───────╯\n```\n\n## Project structure\n\n```\nnteract/nteract\n├── src/                    # Shared UI code (React components, hooks, utilities)\n│   ├── bindings/          # TypeScript types generated from Rust (ts-rs)\n│   ├── components/\n│   │   ├── ui/            # shadcn primitives (button, dialog, etc.)\n│   │   ├── cell/          # Notebook cell components\n│   │   ├── outputs/       # Output renderers (stream, error, display data)\n│   │   ├── editor/        # CodeMirror editor\n│   │   ├── isolated/      # Iframe security isolation (IsolatedFrame, CommBridgeManager)\n│   │   └── widgets/       # ipywidgets controls\n│   ├── hooks/             # Shared hooks (useSyncedSettings, useTheme)\n│   ├── isolated-renderer/ # Code that runs inside isolated iframes\n│   ├── lib/               # Shared utilities (cn(), dark-mode, error-boundary)\n│   └── styles/            # Global stylesheets\n├── apps/                   # App entry points\n│   ├── notebook/          # Desktop notebook Tauri app\n│   ├── notebook-cloud/    # Hosted notebook worker (Cloudflare)\n│   ├── elements/          # Elements design system catalog\n│   ├── mcp-app/           # MCP widget dev app\n│   └── renderer-test/     # Isolated renderer test harness\n├── packages/               # Shared npm packages\n│   ├── notebook-host/     # Notebook host shell\n│   ├── runtimed/          # Node/NAPI daemon client\n│   ├── runtimed-node/     # Node bindings for daemon\n│   ├── sift/              # Sift visualization renderer\n│   └── odometer/          # Odometer component\n├── crates/                 # Rust code\n│   ├── runt/              # CLI binary\n│   ├── runtimed/          # Background daemon\n│   ├── runtimed-py/       # Python bindings for the daemon\n│   ├── runtimed-wasm/     # WASM Automerge bindings for frontend\n│   ├── notebook/          # Notebook Tauri app crate\n│   ├── notebook-doc/      # Automerge document operations\n│   ├── notebook-protocol/ # Notebook wire protocol types\n│   ├── notebook-sync/     # Notebook sync layer\n│   ├── kernel-launch/     # Shared kernel launching API\n│   ├── kernel-env/        # Environment progress reporting\n│   ├── runt-mcp/          # Rust-native MCP server\n│   ├── runt-trust/        # Notebook trust extraction\n│   ├── runt-workspace/    # Workspace detection utilities\n│   ├── runtimed-client/   # Shared client library for daemon\n│   ├── repr-llm/          # LLM-friendly text summaries of visualizations\n│   ├── xtask/             # Build automation tasks\n│   └── mcp-supervisor/    # nteract-dev MCP server (proxies runt mcp + dev tools)\n├── python/                 # Python workspace (uv)\n│   ├── runtimed/          # PyPI: runtimed (Python bindings)\n│   ├── nteract/           # PyPI: nteract (thin launcher for `runt mcp`)\n│   ├── gremlin/           # Stress-testing agent\n│   ├── prewarm/           # Environment prewarm script\n│   ├── dx/                # Developer utilities\n│   ├── nteract-kernel-launcher/ # Kernel launcher for hosted notebooks\n│   ├── pr-reviewer/       # PR review agent\n│   └── safari-timeline/   # Safari timeline parser\n├── plugins/                # Agent plugin distribution\n│   └── nteract/           # Codex plugin package\n```\n\n## Development\n\n### Prerequisites\n\n| Tool | Version | Install |\n|------|---------|---------|\n| Node.js | 22.13+ | https://nodejs.org |\n| pnpm | 11.9+ | `corepack enable` |\n| Rust | 1.94.0 | https://rustup.rs (version managed by `rust-toolchain.toml`) |\n\n**Linux only:** Install GTK/WebKit dev libraries:\n```bash\nsudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev libxdo-dev \\\n  libssl-dev libayatana-appindicator3-dev librsvg2-dev\n```\n\n### Quick start\n\n```bash\ncargo xtask dev\n```\n\n### Development workflows\n\n| Workflow | Command | Use when |\n|----------|---------|----------|\n| One-shot setup + dev | `cargo xtask dev` | First-time setup plus daemon + app in one command |\n| Hot reload | `cargo xtask notebook` | Iterating on React UI |\n| Standalone Vite | `cargo xtask vite` | Multi-window testing (Vite survives window closes) |\n| Attach to Vite | `cargo xtask notebook --attach` | Connect Tauri to already-running Vite |\n| Debug build | `cargo xtask build` | Full debug build (frontend + rust) |\n| E2E debug build | `cargo xtask e2e build` | Debug build with built-in WebDriver server |\n| Rust-only build | `cargo xtask build --rust-only` | Rebuild rust, reuse existing frontend |\n| Run bundled | `cargo xtask run notebook.ipynb` | Run standalone binary |\n| Lint (check) | `cargo xtask lint` | Check formatting and linting across Rust, JS/TS, Python |\n| Lint (fix) | `cargo xtask lint --fix` | Auto-fix formatting and linting |\n| Dev daemon | `cargo xtask dev-daemon` | Run per-worktree dev daemon |\n| Artifact status | `cargo xtask artifacts status` | Check generated WASM, renderer, and MCP widget artifacts |\n| Install nightly (Linux/headless) | `./scripts/install-nightly` | Build + install runtimed + runt + nteract-mcp as the local nightly. Refuses on macOS and when an app bundle is installed. |\n| Release .app | `cargo xtask build-app` | Testing app bundle locally |\n| Release DMG | `cargo xtask build-dmg` | Distribution (usually CI) |\n| Generate icons | `cargo xtask icons [source.png]` | Generate icon variants from source image |\n\n`cargo xtask dev` runs the first-time bootstrap (`pnpm install` + `cargo xtask build`),\nstarts the per-worktree dev daemon, waits for it to be ready, and then launches the\nnotebook app. For repeat launches, use `cargo xtask dev --skip-install --skip-build`.\n\n### Build order\n\nThe UI must be built before Rust because `crates/notebook` embeds assets from `apps/notebook/dist/` via Tauri.\n\n### Common commands\n\n```bash\npnpm build                          # Build notebook UI\ncargo test                          # Run Rust tests\npnpm test:run                       # Run JS tests\ncargo xtask artifacts status         # Check generated artifact readiness\ncargo xtask artifacts ensure runtime # Rebuild only runtimed-wasm when needed\ncargo fmt                           # Format Rust\nvp check --fix                      # Lint + format JS/TS\ncargo clippy --all-targets -- -D warnings               # Lint Rust\n```\n\n## Library crates\n\nThe underlying Rust libraries are published to crates.io:\n\n- [`jupyter-protocol`](https://crates.io/crates/jupyter-protocol) — Jupyter messaging protocol\n- [`jupyter-zmq-client`](https://crates.io/crates/jupyter-zmq-client) - Jupyter kernel interactions over ZeroMQ\n- [`nbformat`](https://crates.io/crates/nbformat) — Notebook parsing\n\n## Contributing\n\nSee `AGENTS.md` for the subsystem map and development guidance. Key entry points:\n\n- `crates/runtimed/AGENTS.md` — architecture, daemon, state ownership\n- `apps/notebook/src/AGENTS.md` — frontend architecture\n- `crates/notebook-wire/AGENTS.md` — wire protocol\n- `cargo xtask help` — all build commands\n\n## License\n\nBSD-3-Clause\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnteract%2Fnteract","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnteract%2Fnteract","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnteract%2Fnteract/lists"}