Famulus Notebook in VS Code

One editing environment for literate AI notebooks, installed from the synced platform folder

The VS Code extension Famulus Notebook opens .fam and .qmd notebooks as a document to read, with the cells’ results in place, and puts everything for working on them into one environment: the artefact of the selected cell beside the notebook, one pane for the cell, its artefact and Famulus on the left, and the debugger below. It works with the Famulus Notebook server on port 5118 (see Notebooks and examples).

The environment

Where	What
Notebook (editor)	The notebook as a document. A cell shows its question and its result. Prose is edited in place; blocks are cut, copied, pasted, duplicated and moved; the + between blocks inserts text, a heading, an empty cell, a cell from a template, a PDAI collection or a Partitur, or asks Famulus at that place.
Artefakt (beside the notebook)	The artefact of the selected cell, for any stored version. A proposed display appears here as a draft until it is applied.
Famulus Notebook (activity bar, left)	One pane, four tabs. Gliederung: sections, cells, runs, goal trees, histories. Zelle: the selected cell as a form over its preamble, with its question and hints; a cell with `ziel: entfalten` also shows the inquiry form, the budget, the rest threshold, the writer grade and, when the filter asks back, the Rückfrage with a field for the answer. Artefakt: how the artefact looks and what it says, by hand (form, fields, a description with measured values) or by instruction to Famulus, with a history per cell. Famulus: composing whole notebooks, sections and cells, `/tangle` and `/weave`. The right end of the menu bar toggles the artefact pane, the debugger and the source, and holds the user menu.
Famulus Debug (panel)	How a run executed: run history, trace, the monitor’s stages, the event log.

The secondary side bar is left free. Keys: ⌥⌘1 source, ⌥⌘2 artefact, ⌥⌘3 Famulus pane, ⌥⌘4 debugger, ⌥⌘0 layouts.

Install on a machine

The package is published in the Syncthing folder umbrella:platform, which every machine has:

~/ai-<machine>/platform/distribution/vscode/
  install-extensions.sh            installs what is published here
  famulus-notebook/
    latest.vsix                    the package (the last three versions are kept)
    manifest.json                  id, version, sha256, built, built_on

~/ai-<machine>/platform/distribution/vscode/install-extensions.sh

The script needs no build, no node and no network. It checks the package against its manifest, installs it into VS Code Insiders (else VS Code, else Cursor; --editor all for every editor found) and says when the window has to be reloaded. --list shows what is published and what is installed. Run it again after Syncthing has delivered a new version.

If platform/distribution/vscode/ is missing on a machine, Syncthing does not share the folder umbrella:platform with it. A machine is shared with a folder when its device ID is in syncthing/src/ai_syncthing/config.py and syncthing/folders.yaml lists it under share_with; then ai-syncthing apply is run on the sharing machine, and the new machine accepts the offered folder once.

What the machine needs

A server	The extension talks to `famulus.serverUrl` (default `http://127.0.0.1:5118`). On a machine that edits notebooks run the server there: `development/famulus-notebook/install.sh --run --launchd`. The extension starts the launchd job itself when nothing answers. A server on another machine can be named in `famulus.serverUrl`; it needs a token (`FAMULUS_TOKEN`, or the file named in `famulus.tokenFile`, default `~/.config/famulus/token`), which is never sent to a server on the same machine. The server reads a notebook by its path on its own disk, so a remote server serves the notebooks that live on that machine.
Data	Cells read the PDAI collections under `$PDAI_COLLECTIONS`. Where the shared volume lacks a collection’s register database, `famulus-notebook/deploy/pdai-overlay.sh` builds a local overlay and `install.sh --launchd` uses it.
A Gemini key	`GEMINI_API_KEY` in the environment, or Famulus: Set Gemini API Key (kept in VS Code’s secret storage). It is used by the Famulus tab and by the artefact chat.

The cell templates and the syntax reference travel inside the package, so Famulus can compose cells on a machine that has no checkout of famulus-notebook.

Users and settings

Profiles live in platform/config/famulus/, in the same synced folder: one file per person (users/<name>.yaml: name, ORCID, institution, defaults for new notebooks, composer model and instructions, layout, the last edited notebook) and one per machine (machines/<host>.yaml: who is active there). Paths are stored relative to ~/ai-<machine>, so a profile works on every machine. Switch users from the person icon in the status bar; edit everything under Famulus: Settings and Profiles.

Where things are

	Path	Synced to
Source	`development/famulus-notebook/vscode/`	the machines of `umbrella:development`
Package and installer	`platform/distribution/vscode/`	every machine
Profiles	`platform/config/famulus/`	every machine
Per-cell history of artefact changes	`<project>/_famulus/gestaltung/<notebook>/<cell>.jsonl`	with the project

Publish a new version

On a machine with the source:

cd ~/ai-<machine>/development/famulus-notebook/vscode
./release.sh --test       # unit tests, build, package, publish into platform/distribution/vscode
./install.sh              # the same, and install here

Raise version in package.json first: an installed extension is replaced only when the version differs. The release stops when the bundle names a machine’s workspace root, so one package serves every machine.