# User Guide


<div class="boopcell boop-raw">

</div>

<div class="boopcell boop-note">

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

</div>

<div class="boopcell boop-note">

## What boopiter is

boopiter is a small notebook app for working with a local LLM, in the
style of [solveit](https://solve.it.com/). You build up a document of
**cells**: run code, write notes, and drop in **prompt** cells that a
local model (via [Ollama](https://ollama.com/)) 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](./index.html) for install/launch).
Point your browser at the address it prints and you’re in.

</div>

<div class="boopcell boop-note">

## 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.

</div>

<div class="boopcell boop-note">

## 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.

</div>

<div class="boopcell boop-note">

## 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.

</div>

<div class="boopcell boop-note">

## 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).

</div>

<div class="boopcell boop-note">

## 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).

</div>

<div class="boopcell boop-note">

## 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.

</div>

<div class="boopcell boop-note">

## 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.

</div>

<div class="boopcell boop-note">

## 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.

</div>

<div class="boopcell boop-note">

## 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

</div>

<div class="boopcell boop-note">

## 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:

  ``` bash
  boopiter nbs/example.ipynb
  ```

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

</div>

<div class="boopcell boop-note">

## 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.

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

</div>