Megillah
Megillah is a planning technology for sustained, nonlinear work conducted with AI collaborators. It keeps purposeful work — its framing, requirements, commentary, evidence, and history — in one durable record that any client can pick up cold.
The product argument and the domain that supports it are documented separately:
Reference for each surface, and for working on Megillah itself:
- Using the CLI
- Serving the Workspace over HTTP
- Connecting an agent through MCP
- The planning browser
- Development
Attribution and provenance
Operations record the contributing Client, read from options or the environment:
| Variable | Meaning |
|---|---|
MEGILLAH_STORE |
Path to the Workspace store |
MEGILLAH_CLIENT |
The Client recorded as provenance |
MEGILLAH_PROJECT |
The Project a command acting in one Project as a whole acts in |
MEGILLAH_HOST |
Interface megillah serve binds |
MEGILLAH_PORT |
Port megillah serve listens on |
MEGILLAH_ALLOWED_HOSTS |
Hostnames the instance answers to, comma separated |
MEGILLAH_LISTENER_URL |
Where megillah mcp reaches the boundary |
MEGILLAH_SHARED_SECRET |
The secret guarding the boundary, which megillah mcp presents |
megillah mcp takes no session Client. One server serves many conversations
across many Assignments, so each contribution is attributed to the Client its
connection negotiated. Nor does it take MEGILLAH_PROJECT: a tool acting in
one Project as a whole names it. Starting it with that configured says so
rather than quietly ignoring it.
Versioning
Megillah's release is derived, not written down. It is read from the commit a
checkout is on: the UTC day that commit was made, and where it falls among
that day's commits — 2026.9.10 for the first, 2026.9.10.1 for the next,
and so on. The build stamps it into the distribution's metadata, and installed
processes report that.
Every merge adds a commit and changes the release, without a manual version edit. An installed distribution keeps the release stamped at build time, even when its source checkout advances. Reinstalling updates that metadata.
Building needs the whole history. A shallow checkout holds only the commits it was given, so it would count fewer of the day's commits than exist and derive a release another commit already carries; the build refuses that rather than answer it. Continuous integration must check out with full depth, and a source archive carries the release already stamped into it, so building from one needs no history at all.
uv run python -m megillah.versioning, run in a checkout, prints the release
that checkout derives.
Publishing a release
Every merge to main whose Verify run passes is published to PyPI under its
release. Nothing is tagged or chosen by hand. Verify builds the source archive
and wheel, installs the wheel alone, and serves the browser from it. Once every
job has passed on main, it uploads that same wheel. The source archive is
built and checked but not published, which keeps each release small.
Releases are unique along main's first-parent line: each commit there
descends from every earlier one, so a later commit made the same day always
counts more of that day's commits. Every commit on that line gets its own
Verify run, and runs on main are never cancelled, so no merge is skipped. A
merge whose run fails is not published, and the next one that passes is.
The upload uses PyPI's trusted publishing: PyPI accepts a job running in this
repository's pypi environment by its GitHub identity, so no credential is
stored. That environment admits only main, so pull requests and other
branches never publish. A published release cannot be replaced, only yanked.
This release identifies artifacts built from this repository. It is not the Workspace schema version and not an outside-process protocol version: the MCP protocol revisions the server speaks are negotiated with each client and move on their own schedule.
License
Megillah is free software under the GNU Affero General Public License, version 3 or later. See LICENSE. Anyone may run, study, change, and share it; anyone who offers a modified Megillah to others over a network must offer them its source under the same terms.
1 maintainer
Release files for megillah 2026.9.18.15
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| megillah-2026.9.18.15-py3-none-any.whl | Python 3 | none | any | Details |
Release files / megillah-2026.9.18.15-py3-none-any.whl
| Download URL | megillah-2026.9.18.15-py3-none-any.whl |
|---|---|
| Size | 985.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
028984ba7d6e65d574baade315d54c708ce1010e4cc38c77a66dbcb037aa1452
|
|
BLAKE2b-256 checksum How to use checksums |
cbb03eb8432aadc237f3b8b796b06677f7061929613b75dad9a22200c72bac32
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
