Frontend Dev

Best for UI/React development. Uses Vite dev server on port 5174.

cargo xtask notebook

Changes to React components hot-reload instantly. The Tauri window loads from localhost:5174 instead of bundled assets.

Requires a dev daemon running. Start one in another terminal first:

# Terminal 1: Start dev daemon
cargo xtask dev-daemon

# Terminal 2: Start the app
cargo xtask notebook

cargo xtask vite + notebook --attach — Multi-Window Testing

When testing multiple notebook windows, closing the first Tauri window kills Vite. To avoid this:

# Terminal 1: Start Vite standalone (stays running)
cargo xtask vite

# Terminal 2+: Attach Tauri to existing Vite
cargo xtask notebook --attach

Close and reopen Tauri windows without losing Vite. Useful for:

• Realtime collaboration testing
• Widget testing across windows
• Avoiding breakage when one window closes

cargo xtask build + run — Debug Build

Builds a debug binary with frontend assets bundled in. No Vite dev server needed.

cargo xtask build           # Full build (frontend + rust)
cargo xtask run             # Run the bundled binary
cargo xtask run path/to/notebook.ipynb

Emits JavaScript source maps for native webview devtools (including inline maps for iframe bundle).

For fast Rust-only iteration after initial build:

cargo xtask build --rust-only   # Skip frontend rebuild
cargo xtask run

Dev Daemon Setup

The notebook app connects to a background daemon. In dev mode, each worktree gets its own isolated daemon.

Two-Terminal Workflow

# Terminal 1: Start dev daemon (stays running)
cargo xtask dev-daemon

# Terminal 2: Run the notebook app
cargo xtask notebook         # Hot-reload mode

Or One-Shot

cargo xtask dev              # Installs deps + builds + starts daemon + launches app
cargo xtask dev --skip-install --skip-build  # Fast repeat

Conductor vs Non-Conductor

Conductor users: Dev mode is automatic. CONDUCTOR_WORKSPACE_PATH is translated to RUNTIMED_WORKSPACE_PATH by xtask commands.

Non-Conductor users: Set RUNTIMED_DEV=1 explicitly:

RUNTIMED_DEV=1 cargo xtask dev-daemon    # Terminal 1
RUNTIMED_DEV=1 cargo xtask notebook      # Terminal 2

Useful Daemon Commands

./target/debug/runt daemon status       # Check daemon state
./target/debug/runt daemon logs -f      # Tail logs
./target/debug/runt ps                  # List running kernels
./target/debug/runt notebooks           # List open notebooks

MCP Server Development

nteract-dev (recommended)

cargo xtask run-mcp

Starts the dev daemon, launches nteract-dev (the dev-only MCP server for this source tree), spawns a child runt mcp, proxies notebook tool calls, watches for file changes, and hot-reloads. Python bindings are rebuilt when the watched Rust paths require it.

For editor config:

cargo xtask run-mcp --print-config

Use nteract-dev as the repo-local MCP server name so it stays distinct from any global/system nteract entry.

Zed Integration

.zed/settings.json (gitignored):

{
  "context_servers": {
    "nteract-dev": {
      "command": "cargo",
      "args": ["run", "-p", "mcp-supervisor"],
      "env": { "RUNTIMED_DEV": "1" }
    }
  }
}

Direct Mode (no proxy)

# Terminal 1: start dev daemon
cargo xtask dev-daemon

# Terminal 2: build bindings + launch MCP server
cargo xtask dev-mcp

nteract-dev Tools

Hot Reload

Watches python/nteract/src/, python/runtimed/src/, crates/runtimed-py/src/, crates/runtimed/src/:

• Python changes — child restarts automatically
• Rust changes — maturin develop runs first, then child restarts

Zed Editor Tasks

The repo includes .zed/tasks.json with pre-configured tasks (use cmd-shift-t):

Common Gotchas

Daemon code changes not taking effect:

1. In dev mode: restart cargo xtask dev-daemon
2. In production mode on macOS: reinstall the nteract Nightly .app (it auto-updates its daemon)
3. In production mode on Linux / headless: run cargo xtask install-nightly
4. Check which daemon: ./target/debug/runt daemon status

App says "Dev daemon not running":

• You're in dev mode but haven't started the dev daemon
• Run cargo xtask dev-daemon in another terminal

Port conflicts with Vite:

• Default port 5174 may conflict across worktrees
• Use cargo xtask build + run to avoid Vite entirely
• Or use CONDUCTOR_PORT for automatic port assignment

Frontend changes not showing:

• With cargo xtask notebook: should hot-reload automatically
• With cargo xtask run: need to rebuild (cargo xtask build)
• With --rust-only: frontend is NOT rebuilt (that's the point)