mooring 0.4.5

Git-free marimo notebook sharing via GitHub

⚓ mooring

Git-free marimo notebook sharing via GitHub.

Mooring is a single-file app (mooring.pyz / mooring.exe) that lets a team of data analysts pull, edit, and push marimo notebooks stored in a shared GitHub repo — without git installed on their machines. All sync happens over the GitHub REST API; the only requirement on an analyst's machine is Python 3.12 or newer.

Double-clicking the app opens a local browser hub: log in to GitHub with a one-time device code, see every team notebook with its sync status, pull the latest, open notebooks in the bundled marimo editor, and push your changes back — one commit per file, with conflicts detected and resolved per file (never silently overwritten).

How it works

• One shared team repo (e.g. your-org/notebooks) holds notebooks/, data/, and reports/ folders. Everyone pulls from and pushes to it.
• No git anywhere. Pull walks the repo tree via the GitHub Git Data API and downloads only changed blobs; push uses the Contents API with the file's last-known SHA, so GitHub itself rejects writes that would clobber someone else's change.
• Conflicts are explicit. Pull never overwrites local edits; push blocks conflicted files, offering per-file resolution.
• Push or propose. Push commits straight to the shared branch; propose sends changes to a personal review branch so they can land via a pull request — protect the branch and propose becomes the only way in.
• Dependencies live with the repo. A repo declares its notebook packages in a pyproject.toml + uv.lock at its root (run mooring init, then mooring deps add <pkg>), version-controlled alongside the notebooks. With uv, notebooks run in that locked environment automatically; mooring itself ships lean (no opinionated analyst stack baked in). For machines with no uv, an admin builds a frozen .pyz whose bundle is generated from that same pyproject.toml — one source of truth, two delivery modes (see build & distribute).
• Works on corporate GitHub. GitHub Enterprise instances are supported (mooring login --host ghe.example.com), and TLS is verified against the OS trust store, so SSL-intercepting proxies with an IT-installed root CA just work.

Install from PyPI

With Python 3.12+ and uv, run Mooring straight from PyPI — no frozen build needed:

uvx mooring                  # run it as a one-off tool
uv tool install mooring      # …or install it as a persistent CLI
pip install mooring          # …or into the active environment

Optional extras

Mooring ships lean; opt-in features live behind extras. Quote the brackets — [...] is a shell glob, so an unquoted mooring[copilot] can expand to nothing:

Extra	Enables
copilot	the AI copilot
pii	NER name detection for the PII guard
pii-spacy	offline name detection (air-gapped teams)

uvx "mooring[copilot]"               # one-off tool run
uv tool install "mooring[copilot]"   # persistent CLI tool
uv add "mooring[copilot]"            # add to your own uv project
pip install "mooring[copilot]"       # plain pip

Combine with a comma ("mooring[copilot,pii]"). Full reference: optional extras.

Documentation

Full docs live in docs/ and build into a searchable site with zensical:

• For users — install Python, run the app, and pull / edit / push notebooks (daily workflow, conflicts, CLI).
• For admins — set up a team: GitHub setup (the repo, OAuth app, client id, scopes), configuration, and build & distribute.
• For developers — architecture and contributing.

Build & preview the docs

uv sync
uv run zensical serve     # live-reloading preview at a local URL
uv run zensical build     # static site into ./site

.github/workflows/docs.yml publishes the site to GitHub Pages on every push to the default branch.

Develop

uv sync                                  # install everything
uv run pytest                            # unit tests (no network needed)
uv run ruff check src tests              # lint
uv run mooring hub                       # run the hub from source

See contributing for the architecture, integration testing, and project conventions.

---

Built with moonlit.