DEMOLAB articles notebooks collections github

Getting started

20th Jun 2026

This guide is meant to be run with a coding agent. Open the repo in Claude Code (or any agent) and say “how do I get started” — it will walk you through these steps interactively, running the commands with you and checking each one works. You can also just follow them by hand.

By the end you’ll have the demo site running locally, understand the core loop, and have published your own first notebook.

Agent: drive this as an interactive session. Run each step’s commands yourself, show the user the result, and confirm before moving on. Don’t dump the whole guide at them — take it one step at a time.

0. Prerequisites

  • A fork of this repo, cloned locally (see the README for the fork link).
  • uv for Python and bun for the site. The toolchain rule: never call python/pip/npm directly — always uv and bun (see CLAUDE.md).

Agent: check uv --version and bun --version first. If either is missing, stop and give the user the one-line install command for their platform before continuing.

1. Orient

This repo is a lab notebook system with one opinionated loop:

a CLI runs an experiment and drops a directory of artifacts → a notebook runner bundles those artifacts → an Astro site publishes a post for each notebook.

You operate it together with your agent. The full contract is in CONTRIBUTORS.md; you don’t need it yet.

2. Install and verify

uv sync
cd src/docs && bun install && cd ../..

Agent: run both, confirm they succeed.

3. See the loop work

Run an existing notebook end to end, then start the site and look at the result:

uv run python src/notebooks/nb000.py
cd src/docs && bun run dev

Open http://localhost:4321 and click into nb000. You’re looking at a post generated from the CLI run you just executed — the figure and the numbers in the prose came straight out of src/artifacts/neuron_cli/ via src/docs/public/notebooks/nb000/.

Agent: start the dev server in the background so the session can continue. Point the user at the nb000 post and explain, in one or two sentences, how the artifact they just generated became that page.

4. Make it yours — name the site

Make the site the user’s before filling it with their own work.

Agent — rename the site:

  • Brand + github link: set PUBLIC_SITE_NAME (the header wordmark, defaults to DEMOLAB) and PUBLIC_SITE_REPO_URL (the header “github” link). Either commit a src/docs/.env with these, or change their defaults in src/docs/src/layouts/Base.astro.
  • Page titles still read “demolab” in a few src/docs/src/pages/*.astro files (the browser-tab <title>s) — update them if that matters.
  • The site URL and base path are set when you publish (step 7).

5. Scaffold your first notebook

This is the point of the workflow: go from an idea to a published result in one session.

Agent: ask the user what they’d like to compute or simulate — keep it small (a function to plot, a tiny simulation, a parameter sweep). Then:

  1. Add a CLI command for it. Either add a subcommand to an existing CLI under src/clis/<tool>_cli/cli.py, or create a new tool directory. Follow “Adding a new notebook” / “Adding a new CLI tool” in CONTRIBUTORS.md exactly — write config.json, output.json, a figure, and pass a manifest to write_output declaring the headline figure and metrics. Model it on src/clis/neuron_cli/cli.py.
  2. Create the notebook runner src/notebooks/nbNNN.py (next free number), modeled on nb000.py (single tool) or nb002.py (mix of tools). Declare its COMMANDS.
  3. Create the post src/docs/content/notebooks/nbNNN.mdx — frontmatter title + date (and optional description, collection, status). Inline values from the generated numbers.json into a short prose explanation + a parameter table.
  4. Run it: uv run python src/notebooks/nbNNN.py, then refresh the site and open the new post with the user.

Keep the first one minimal — the goal is for the user to watch their own idea become a published page, not to build something elaborate.

6. Clear the demo content

With your own notebook working, delete the shipped demo — the three Example: collections — so the site is yours, not a copy of demolab.

Agent: remove the example content (do this after the user’s first notebook works, so it’s there as a template while scaffolding):

  • Example CLIs: src/clis/neuron_cli, src/clis/mujoco_cli, src/clis/streamlit_cli
  • Demo notebooks: src/notebooks/nb000.py–nb003.py, their posts src/docs/content/notebooks/nb00*.mdx, the copied assets in src/docs/public/notebooks/, and the runs under src/artifacts/
  • Example articles: src/docs/content/articles/ar000.mdx (neuron) and ar003.mdx (streamlit)

Keep the Documentation articles if you want them as your site’s own docs — ar001 (intro, worth rewriting for your project), ar002 (the SVG how-to), and the guides ar004–ar007. Note: ar004–ar007 are wired to the triggers in CLAUDE.md, so if you delete a guide, drop its matching trigger too.

7. Publish it

The site deploys to GitHub Pages automatically on every push to main (.github/workflows/deploy.yml). Two one-time steps for your fork:

  1. Point the site at your fork. In src/docs/astro.config.mjs, set site to https://<your-username>.github.io and base to /<your-repo-name>.
  2. Enable Pages. On GitHub: Settings → Pages → Build and deployment → Source: GitHub Actions.

Then commit and push to main. Your notebook goes live at https://<your-username>.github.io/<your-repo-name>/.

Agent: make the astro.config.mjs edit for the user (ask for their username/repo), then walk them through enabling Pages and pushing. Confirm the Actions run succeeds.

8. Where to go next

  • CONTRIBUTORS.md — the CLI ↔ notebook contract and the procedures for adding notebooks and tools.
  • The Migrating an existing repo doc (ar005.md) — bring an existing script or simulation into this structure.
  • The Adopting features from upstream doc (ar007.md) — pull new feature ideas from upstream demolab and have your agent reimplement the ones you want, your way.