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, on FastAPI and uvicorn
- 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_WORKOS_CLIENT_ID |
The WorkOS environment a guarded instance logs its operator in through |
MEGILLAH_WORKOS_API_KEY |
That environment's API key |
MEGILLAH_OPERATOR_EMAIL |
The one email address a guarded instance admits |
MEGILLAH_BROWSER_URL |
The address a browser opens a guarded instance at |
Versioning
A release names the UTC day its commit was made and the Verify run that built
it: 2026.9.18.413 is run 413, on a commit made on 18 September 2026. Nobody
writes it down. Continuous integration tags the commit with its release, and
the build reads that tag through hatch-vcs
into the distribution's metadata, which installed processes report.
Each merge to main gets its own Verify run, and GitHub numbers runs in the
order they start, so releases increase along main. Releases published
before this scheme counted the day's merges instead, so a day's first was
2026.9.10; run numbers had already passed those counts, so every earlier
release orders below.
A tagged commit builds its release from any checkout, shallow included, and a
source archive carries its release in its metadata, so building from one needs
no history. Any other commit builds as a development release, such as
2026.9.18.414.dev3+g1a2b3c4 three commits past the last tag, or
0.1.dev3+g1a2b3c4 where no tag has been fetched. An installed distribution
keeps the release it was built with, even when its checkout moves on;
reinstalling updates it. git tag --points-at HEAD names the release of a
tagged checkout.
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 tags the commit it checked
out, builds the source archive and wheel, installs the wheel alone, and serves
the browser from it. Once every job has passed on main, it pushes the tag to
GitHub and then uploads that same wheel, so every published release has its
tag. The source archive is built and checked but not published, which keeps
each release small.
Runs on main are never cancelled, so no merge is skipped. A merge whose run
fails is neither tagged nor published; a re-run keeps its run number, so it
publishes under the same release. Run numbers belong to verify.yml: renaming
it would start them again, below releases already published, and PyPI's trusted
publisher names it too.
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 tag or 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.23.658
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.23.658-py3-none-any.whl | Python 3 | none | any | Details |
Release files / megillah-2026.9.23.658-py3-none-any.whl
| Download URL | megillah-2026.9.23.658-py3-none-any.whl |
|---|---|
| Size | 613.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4b7a81fa963fe2c7ea524d1e926c9f3d96a54876d7808a980454d0f9ececccd4
|
|
BLAKE2b-256 checksum How to use checksums |
779ef08724b48d18c759bfdebddea2107025d478b74be62be62cc5cffb5badee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
