Installation
Pick the shortest route for your case. To learn with an AI assistant you need only Node: the assistant
starts the Studium server with npx, and no checkout is needed. Teachers who prepare and approve courses,
and contributors, install from a checkout. The first session needs no model API key.
Choose how you install
| You want to | Route | You need |
|---|---|---|
| Learn with an AI assistant (Codex, Claude Code, Copilot, Cursor, OpenCode, Claude Desktop) | Add the server to your assistant | Node |
| Learn in Claude Code, with the lesson agents and the skills | Install the Claude Code plugin | Node, Claude Code 2.1.275 or later |
| Play lessons in a visual pane | Install the VS Code extension | VS Code |
| Prepare and approve courses, or contribute | Install from a checkout | Git, Node, pnpm; Python for the teacher tools |
| Open a portable activity a teacher prepared | nothing: open its index.html (see Activity to report) |
a recent browser |
Only a checkout gives you:
- the demo lessons of
fixtures/; - the teacher tools (Python), which prepare, check and approve a course;
- the skills for assistants other than Claude Code (the plugin brings them to Claude Code);
- the Observatory and the teacher dashboard (see Follow a class).
Requirements
| Tool | Version | Route | Check with |
|---|---|---|---|
| Node | 22 LTS (20 and later accepted) | server, plugin, checkout | node --version |
| Claude Code | 2.1.275 or later | plugin | claude --version |
| VS Code | 1.95 or later | extension | Help, About |
| Git | any recent | checkout | git --version |
| pnpm | 9.15.9 | checkout | pnpm --version |
| Python | 3.12 or later | checkout, teacher tools only | python3.12 --version |
The extension carries its own server and needs no separate Node. If pnpm is missing, corepack enable
(shipped with Node) or the pnpm installation guide provides it. On a stock
macOS, python3 is often 3.9, which is too old for the teacher tools.
Where the packages are
Since version 0.6.0, the server and the extension are on public registries:
| What | Registry | Name |
|---|---|---|
| MCP server | npm | studium-mcp |
| MCP server, listed for assistants | MCP Registry | io.github.HolobiomicsLab/studium |
| VS Code extension | Visual Studio Marketplace | holobiomicslab.studium-vscode |
| VS Code extension for VSCodium, Cursor and Gitpod | Open VSX | holobiomicslab.studium-vscode |
The Claude Code plugin is on no registry: Claude Code reads it from this repository, which is public. It
starts its server with npx -y studium-mcp.
On a machine that cannot reach a registry, use the two files attached to a GitHub release:
lesson-mcp.cjs, started withnode /path/to/lesson-mcp.cjswherever this documentation writesnpx -y studium-mcp;studium-vX.Y.Z.vsix, installed withcode --install-extension studium-vX.Y.Z.vsix.
The repository is public: cloning it, installing the plugin and downloading release files need no account.
Add the server to your assistant
You need Node 20 or later. npx fetches the server the first time; there is nothing else to install.
LITELLM_BASE_URL= (empty) tells Studium to call no judge model, even if your shell defines one.
| Assistant | Command or file |
|---|---|
| Claude Code | claude mcp add --scope user studium -e LITELLM_BASE_URL= -- npx -y studium-mcp |
| Codex | codex mcp add studium --env LITELLM_BASE_URL= -- npx -y studium-mcp |
| Copilot in VS Code | code --add-mcp '{"name":"studium","command":"npx","args":["-y","studium-mcp"],"env":{"LITELLM_BASE_URL":""}}' |
| Cursor | .cursor/mcp.json or ~/.cursor/mcp.json, see Connect Cursor |
| OpenCode | opencode.jsonc, see Connect OpenCode |
| Claude Desktop | claude_desktop_config.json, see Connect your assistant |
Check the server itself:
npx -y studium-mcp --version
npx -y studium-mcp --help
Both answer without starting the server. Then check that your assistant is connected: Connect your assistant.
Install the Claude Code plugin
The plugin studium adds the server, the twelve skills of skills/ and the two lesson agents in one step:
claude plugin install studium --marketplace HolobiomicsLab/studium
Inside a session, /plugin install studium --marketplace HolobiomicsLab/studium does the same. How the
skills and agents are named under the plugin, and the two-step, update and removal commands, are in
Connect Claude Code.
Install the VS Code extension
From the Visual Studio Marketplace or Open VSX:
code --install-extension holobiomicslab.studium-vscode
Or from a release file: code --install-extension studium-vX.Y.Z.vsix. The extension contains the server and
the renderers. Lessons are not inside it: it reads your personal library (~/.studium/library) or the
folder you pick. What it offers is described in VS Code.
Install from a checkout
This route is for teachers who prepare and approve courses, and for contributors.
Get the code and build
git clone https://github.com/HolobiomicsLab/studium.git
cd studium
./setup.sh
setup.sh is safe to re-run. It checks Node and pnpm, installs the workspace, builds the workspace
libraries, copies the offline renderers (KaTeX, Vega, 3Dmol) into the extension, builds the extension and
verifies the outputs. The manual equivalent is:
pnpm install --frozen-lockfile
pnpm build:libs
pnpm --filter studium-vscode vendor
pnpm --filter studium-vscode build
The last command writes apps/studium-vscode/dist/extension.js and
apps/studium-vscode/dist/lesson-mcp.cjs. The second file is the self-contained Studium MCP server, the
same file as lesson-mcp.cjs in a release. An assistant starts it with node (see
Connect your assistant); it needs no global tsx.
Check the server without any client
node apps/lesson-mcp/scripts/headless_smoke.mjs
A bare MCP client starts the server, lists its tools, plays a shipped lesson and prints
all 19 assertions passed. The smoke test keeps nothing on disk. It proves the server works; it does not
prove that a given assistant is connected.
Other ways to run the server
| Use | Command |
|---|---|
| From sources, for development | pnpm --filter @studium/lesson-mcp start |
| Standalone single file | pnpm --filter @studium/lesson-mcp bundle, which writes apps/lesson-mcp/dist/studium-mcp.cjs |
| Local HTTP API instead of MCP | pnpm --filter @studium/lesson-mcp api (see HTTP API) |
How a release is built and published is in Release.
Build the VS Code extension
pnpm --filter studium-vscode package
code --install-extension apps/studium-vscode/studium.vsix
package vendors the renderers, builds, and runs the pinned vsce dev dependency. A colleague can install
the VSIX without a checkout. Developers can instead open apps/studium-vscode in VS Code and press F5.
Add the teacher tools (Python)
From the repository root, in a virtual environment (never the system Python):
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python tools/experience_packet.py --help
experience_packet.py offers passages, prepare, check, bundle, approve and receipt. The
last records a review receipt for a lesson you send back, without approving it; approve refuses a
to_fix verdict and points to it. Continue with the teacher guide.
Scientific libraries a course capsule needs are installed in that capsule's own environment, at the
versions it declares.
Windows
The checkout commands are written for macOS and Linux. On Windows:
- create the environment with
py -3.12 -m venv .venvand replace.venv/bin/pythonwith.venv\Scripts\python.exe; - in PowerShell, set a variable with
$env:NAME="value"before the command instead ofNAME=value command; setup.shand the extension'svendorscript use Unix tools (mkdir -p,cp): build under WSL, or install a VSIX built elsewhere. Do not mix Windows and WSLnode_modules;- the discovery links in
.claude/skillsand.agents/skillsare symlinks, which a Windows checkout may not keep; point your assistant atskills/<name>/SKILL.mddirectly.
The Windows path has not been run end to end.
Where Studium keeps your lessons and progress
The server started by an assistant uses these defaults, whatever the route. Each can be changed with an environment variable in the assistant's configuration; the full list is in Configuration.
| What | Default | Variable |
|---|---|---|
| Studium home | ~/.studium |
STUDIUM_HOME |
| Lessons built for you | ~/.studium/library |
STUDIUM_HOME (BUNDLES_ROOT only adds a folder looked up first) |
| Durable progress and reviews | ~/.studium/data |
STUDIUM_DATA_DIR |
| Keep everything in memory (tests, demos) | off | STUDIUM_EPHEMERAL=1 |
Learner folders on disk are named by a pseudonym, never by your learner id. The VS Code extension keeps its own progress in VS Code's extension storage; see VS Code.
Update
| Route | Update |
|---|---|
Server with npx |
restart the assistant. npx may reuse a copy it already fetched: npx -y studium-mcp@latest --version asks npm for the newest |
| Claude Code plugin | claude plugin marketplace update holobiomicslab, then claude plugin update studium@holobiomicslab |
| VS Code extension | from a marketplace, VS Code updates it; from a file, install the newer .vsix |
| Checkout | git pull, then ./setup.sh |
Then restart or reconnect the MCP server in your assistant. A server file built or downloaded before the
update lacks recent tools without any other symptom: ask your assistant to call get_server_info, which
reports the version, whether the build is source or bundled, its build date and the tool list. Your
lessons and progress in ~/.studium are not touched by an update.
Remove your data
Your assistant can erase one lesson's progress with forget_session, only when you ask; it also
erases your cross-lesson profile and study record (your review schedule), and cannot be undone. Asked to
erase all your data, it erases every lesson's progress too. Its reply names what stays: the lessons in
your library and their prepared sources. To remove everything the assistant-side server kept, delete the
Studium home folder (~/.studium by default). In VS
Code, Studium: Forget my data erases what the extension keeps. Exported reports and your assistant's own
history are separate copies. More in Privacy and limits.