User Guide

A walkthrough of the boopiter interface – what the buttons do, how cells work, and the keyboard shortcuts – for people who just want to use it. For how the code is organized, see the module pages in the sidebar.

What boopiter is

boopiter is a small notebook app for working with a local LLM, in the style of solveit. You build up a document of cells: run code, write notes, and drop in prompt cells that a local model (via Ollama) answers inline. Everything runs on your own machine.

It runs in your browser but is driven by a local server you start from the command line (see the home page for install/launch). Point your browser at the address it prints and you’re in.

Starting the server

Launch boopiter from the repo root:

boopiter [notebook.ipynb] [--port PORT]

notebook.ipynb and --port (default 8000) are both optional – omit the filename to start with a blank notebook.

Token authentication is on by default. Every code cell runs with this process’s own OS permissions, so an unauthenticated boopiter reachable on a shared network is equivalent to an open shell – the server refuses that by default. On startup it prints:

boopiter is token-gated. Open:

    http://localhost:8000/?token=<a long random string>

Open that exact URL once; it signs you in and remembers you (a cookie) for future visits, so you don’t need the token again until the cookie expires or you use a different browser. If you land on a sign-in page instead, paste the token there. Restarting the server from within the app (the restart-kernel button) keeps the same token, so an in-app restart never signs you out.

Only pass --no_auth on a network you fully trust (e.g. localhost-only, no shared Wi-Fi) – it disables the token check entirely.

The screen

The window has three parts:

  • The top bar (across the top) – the file menu and current filename on the left; model and kernel controls on the right.
  • The notebook (the middle) – your stack of cells.
  • The composer (the bottom) – a text box for typing the next cell.

The top bar

Left side: a menu (☰) with New / Open / Save / Download / Restart Server, the boopiter logo, and the current notebook’s filename. (You can also right-click anywhere on the page to get the same menu.)

Right side, left to right:

  • Plugin icons – small live indicators contributed by plugins. The built-in one is a system monitor; hover it for CPU / RAM / GPU sparklines.
  • Tools (wrench) – choose which Python functions the LLM may call while answering (see Prompt cells).
  • Model (brain) – pick the model that answers prompt cells (see Choosing a model).
  • Help (?) – opens the keyboard-shortcut reference.
  • Interrupt kernel (⊗) – stop the code or reply that’s currently running.
  • Restart kernel (↻) – clear the Python session and start fresh.
  • Run all (▶) – run every code cell top to bottom (see Running code).
  • Theme (moon/sun) – switch light/dark.

Cells and cell types

Every cell is one of four types you can author, plus one the app generates:

  • Code – Python, run in a shared kernel; output appears beneath it.
  • Note – Markdown prose, rendered when you’re not editing it.
  • Prompt – a question for the LLM; running it produces an…
  • Assistant – reply (generated for you – you don’t create these directly).
  • Raw – text passed through untouched.

Selecting a cell: click its header (the small id/label strip at the top of the cell). The selected cell shows a highlighted left border, and the command-mode shortcuts below act on it.

Changing a cell’s type: select the cell and press m (note), y (code), or r (raw). For a new cell, choose the type on the composer tabs before you add it (next section).

Adding cells with the composer

The composer at the bottom of the page is the main way to add cells:

  1. Pick the type on the tabs – Code / Note / Prompt / Raw.
  2. Type into the box.
  3. Press Shift-Enter (or click Boop) to append it to the notebook.

To insert a cell in the middle instead, select a cell and press a (insert above) or b (insert below).

Editing cells

Click a cell’s body to edit it. Code cells open a code editor (syntax highlighting; Cmd/Ctrl + / toggles comments on the selected lines); note, prompt, and raw cells get a plain text box.

  • Shift-Enter (or Ctrl/Cmd-Enter) saves the cell – and runs it, if it’s code or a prompt.
  • Esc cancels the edit and reverts.
  • There’s also a shortcut to split the current cell at the cursor into two – press ? in the app for the exact keys.

Note: an edit isn’t saved until you Shift-Enter it (or run it), so a half-typed change won’t silently persist.

Running code

Run a single code cell with its Run (▶) button, or by pressing Shift-Enter while editing it. Output streams in live beneath the cell, and the cell is timestamped when it runs.

Run all (the ▶ button in the top bar) runs every code cell top to bottom, one at a time, scrolling each into view as it goes, and stops if a cell raises an error.

The kernel is shared across cells (like Jupyter), so names defined in one cell are available in later ones. Use Interrupt (⊗) to stop a long-running cell, or Restart kernel (↻) to wipe the session and start over.

Prompt cells and the LLM

A prompt cell is a question for the local model. Run it (Run ▶ or Shift-Enter) and the reply streams into an assistant cell just below it.

Choosing a model – the brain icon in the top bar opens the model picker:

  • Standard model – answers ordinary prompts.
  • Reasoning model – a “thinking”-capable model (only models Ollama reports as such are listed), with an L / M / H effort control beside it.
  • Click the brain icon itself to toggle which of the two answers your prompts; it turns cyan while the reasoning model is active.

Tools – the wrench menu lets the model call selected Python functions while it answers (they run in your kernel). Pick which tool sources are offered there.

boopiter detects whatever models ollama list knows about when it starts; if qwen2.5-coder is installed, it’s the default.

Organizing the notebook

With a cell selected (not being edited), single keys act on it:

  • a / b – insert a cell above / below
  • j / k (or ↓ / ↑) – move the selection
  • the arrow-up / arrow-down icons on a cell – move the cell itself
  • c / x / v – copy / cut / paste
  • dd (press d twice) – delete the selected cell
  • the eye icon – show / hide a cell’s content
  • w – pull the code blocks out of an assistant reply into their own code cells

Saving and loading

  • Save – press s, or use the file menu (☰) / right-click menu; a toast confirms.

  • Open / New / Download – from the file menu or right-click.

  • You can also launch boopiter with a notebook already loaded:

    boopiter nbs/example.ipynb

Notebooks are ordinary .ipynb files – they open in Jupyter too.

Keyboard shortcuts

Press ? (or the help icon) any time for this list in the app. Command-mode shortcuts work when you are not editing a cell.

Key Action When
a / b Insert cell above / below command
j / k, ↑ / ↓ Move selection command
m / y / r Set type: note / code / raw command
c / x / v Copy / cut / paste command
dd Delete selected cell command
s Save notebook command
w Pull code blocks from a reply command
Shift-Enter Save, and run code/prompt cells editing
Esc Cancel edit editing
Cmd/Ctrl + / Toggle comment editing (code)