labnotes
Browse experiment designs, notes, and run data from a folder.
uvx labnotes server
A project's root is the folder holding its .labnotes.toml. labnotes init
writes one with the default layout:
[experiments]
path = "{experiment}"
[files]
path = "{experiment}/files/"
[runs]
path = "{experiment}/runs/{run}"
Each path is relative to the root. {experiment} and {run} stand for folder
names: the experiments path must use {experiment}, and the runs path both.
labnotes reads the file from the working folder, or from the path given with
-c.
When experiment.toml sits next to .labnotes.toml, the root is the one
experiment, named after its folder. Paths then drop {experiment}: files
default to files/ and runs to runs/{run}.
labnotes experiments reads three tables from those paths:
experiments:name, andconfig, the experiment'sexperiment.tomlas JSON. An experiment is a folder matching the experiments path that holds anexperiment.toml, files or runs.files:experiment,filename,path,ctime,mtime.runs:experiment,id,folder,created,ended,exit_code,error,stdout,stderr, andparamsas JSON, read from each run folder'srun.json.
Keys come from folder names, so renaming a folder renames its rows on the next read. Paths are relative to the root, and times are UTC ISO 8601.
labnotes experiments # name, last_run, created, files, runs
labnotes experiments foo # the same, plus config
labnotes experiments foo runs # foo's runs, oldest first
Each takes --format table or --format json, which print rows and exit.
Without --format, they open a browser in a terminal: the experiment list,
Enter to open one, Escape to go back. foo and foo runs open straight on
foo, which shows its runs grouped by invocation; Enter expands or collapses
one. Piped, they print a table.
labnotes experiments new [NAME] creates an experiment folder with a starter
experiment.toml, picking a random name if you give none. new itself can't
be an experiment name.
labnotes experiments foo run runs foo from its experiment.toml, in the
experiments folder:
name = "Model and effort"
command = "uv run scripts/study.py --output {run_dir}"
repeats = 5
[params]
model = ["opus", "sonnet"]
effort = ["low", "high"]
name is optional: a display name for the experiment, shown in the live view
and as display_name in experiments. The folder name stays the key, so
renaming the experiment means editing name.
Each combination of [params] runs repeats times, round-robin. Only runs
that exit 0 count, so running again fills in what failed or never ran.
Each run gets a new run folder. command runs in a shell from the root, with
{run_dir} replaced by the run folder's absolute path. Pass it to the
script so it writes its outputs there.
Each param is appended as --name value, with the name as written (use
source-language for a --source-language flag), booleans as 0 or 1, and lists
and tables as JSON. labnotes writes run.json (params, created, ended, exit
code), stdout.log and stderr.log to the run folder.
To exclude a run, add "excluded": true and an optional "reason" to its
run.json. An excluded run doesn't count toward repeats, so the next run
replaces it; both show as columns in runs.
In a terminal, run shows a live table of runs (status and time) and stays
open when they finish; Ctrl-C quits. Elsewhere, it prints a
line per event instead.
--concurrency Nruns N at a time (default 1).-e PATHreads another file instead ofexperiment.toml.- With runs going, Ctrl-C asks first. Enter (or a second Ctrl-C) leaves them
running.
sstops the running scripts and records their end, then kills any still going 5 seconds later. Escape goes back. SIGTERM stops them likes. - A second
runof the same experiment fails while the first holds the lock. - It exits 0 even if runs fail; the summary line counts failures. If it can't start or reach the daemon, it prints the cause on one line and exits 1.
labnotes server serves a local site at http://127.0.0.1:8000 from the same
.labnotes.toml: a table of experiments, and a page per experiment with its
params, its markdown files, progress per cell of the params grid, and every
run so far. A cell is full once it has repeats runs that exited 0 and aren't
excluded, the same count run uses. The project is watched, so a reload shows
new runs and edited notes. Python blocks in a note run with the root as the
working folder.
-h/--host and -p/--port change where it listens; -h 0.0.0.0 (or a
Tailscale IP) serves beyond localhost. Every other uvicorn option passes
through: --reload, --workers, --proxy-headers, --root-path, the
--ssl-* set, and the rest. labnotes server --help lists them.
Agent skill
npx skills add thekevinscott/labnotes
The skill tells a coding agent to run labnotes context, which prints a usage
guide for the installed version.
1 maintainer
Metadata
1 maintainer
Release files for labnotes 0.0.101
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| labnotes-0.0.101.tar.gz | 138.5 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| labnotes-0.0.101-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 247.1 kB
Release files / labnotes-0.0.101.tar.gz
| Download URL | labnotes-0.0.101.tar.gz |
|---|---|
| Size | 138.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a3a8fa7a9ab885cfe122ac9b9c69cc00df53c1cdbc6b2ab1862ce60a4e321d4e
|
|
BLAKE2b-256 checksum How to use checksums |
4e12c6f179dfe82fe49fa49871473ea368887c5d61ac02d02795caf632dd5d3b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logRelease files / labnotes-0.0.101-py3-none-any.whl
| Download URL | labnotes-0.0.101-py3-none-any.whl |
|---|---|
| Size | 108.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cc3da9e8e32388555b47d45aaf33bfc06492421721219568efb75a65f93ef00f
|
|
BLAKE2b-256 checksum How to use checksums |
9f4b48e10829ae86da043f9a3a0f649ce82c6e50e7f60ea3646da89d8661ed35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logSecurity for labnotes 0.0.101
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for labnotes-0.0.101.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
