Skip to main content

hakodesh

Host-agnostic Python CLI and SDK. After pip install hakodesh the user book is empty. Your LLM or agents mint spells, enchantments, wards, and combos as they need them. Version 0.8 adds package-owned, explicit Claude Code setup; 0.8.1 adds an opt-in persistent reader. Installation never edits host settings or installs hooks.

PyPI name, import, and command: hakodesh.

Install

pip install hakodesh
hakodesh --help
hakodesh אינסטיטוי --help

Data home: HAKODESH_HOME or the platform user-data directory for hakodesh. Never ~/spells.

Kernel commands

These are the runtime, not starter spells:

Command What it does
hakodesh רעקענסוי User artifacts in the book (empty at install)
hakodesh דירעקסי "<intent>" Rank minted names plus kernel commands
hakodesh דיקסי <name> [args...] Cast a minted spell by name
hakodesh פערקוסי <name> --kind spell|enchantment|ward|combo [--like <name> | --from <path>] Scaffold into the book, or mint from a source file (preview; --confirm writes)
hakodesh סקריפסי Verify HMAC chain; --tail N
hakodesh סיגנאווי Cast ledger stats
hakodesh סיגנאווי seal RFC 6962 Merkle seal (preview; --confirm writes; verify)
hakodesh אינקאנטאווי bind|lift <name> --settings <path> Bind or lift a minted enchantment
hakodesh קוסטודיווי status|lock|unlock|check <name> Fail-closed ward kernel
hakodesh קוניונקסי seal|cast|list [name] Sealed pipelines of minted spells
hakodesh אינסטיטוי ... Preview and explicitly manage supported host setup; see Onboarding
hakodesh reader persistent ... Import and query reader state only with caller-supplied paths and scope
hakodesh קונסולטאווי ... Run the local reader functional pilot; it is not a production remote reader

--like on an empty book uses the kind template in the wheel. After one spell exists, --like <that> copies its shape.

Every mint and cast emits hakodesh.event/v1. Akashic is SHA-256 linked and HMAC-SHA256 signed. Grimoire is Merkle-sealed with the same chain key. The keystore is $HAKODESH_HOME/keys (0700/0600), minted on first seal, never in the wheel.

Notifications default to none. The package does not write LaunchAgents or editor hooks during installation. Claude Code hooks are written only by hakodesh אינסטיטוי claude apply --confirm.

Persistent reader (opt-in)

Start with hakodesh reader persistent --help. Persistent commands require an explicit --state path and, for source operations, the source file, its inventory, and caller-supplied source, provider, and scope identifiers and revisions. The package does not choose a state location or migrate a reader state because the package version changed.

ingest consumes a saved raw-worker/v1 result or saved controlled worker envelope. It does not contact a model provider. Query, history, expansion, and dossier commands read retained state without making semantic provider calls. Saved worker imports and caller labels are not live provider telemetry; provider attempts or billing are reported only when linked evidence supports them.

The reader reports inventory coverage by unit. It checks quoted text against retained source bytes and marks unresolved quotes and missing units visibly. A refresh keeps historical claims and evidence, rechecks changed units, and marks claims with invalidated dependencies for review. These checks provide traceable local state; they do not establish semantic completeness.

The existing hakodesh קונסולטאווי ... and hakodesh-reader-pilot local pilot remain available with their existing behavior. See 0.8.1 release notes and the reader guide.

עלוקווענטיא: the dialect

The Alter Rebbe's Tanya is known, to those who sit with it closely, for a rigor that does not stop at the sentence or even the word: every letter is weighed, none placed by habit or convenience. Read as more than a style, this is bitul — a mind that has stopped inserting its own preference between a letter and what that letter is meant to carry.

hakodesh's protocol is built the same way, for a reason that lives in the code, not the analogy. dialectus.generate() is the only source of a token. Not one string in this dialect — no kernel verb, no spell name, no status, no ward — was chosen by someone looking at it and deciding it sounded right. Each is the mechanical output of one fixed table of letter mappings, applied without exception to a Latin root picked for what it means, never for how its transliteration will look. The test suite enforces this literally: regenerating the whole lexicon from its lemmas must reproduce a golden snapshot byte for byte, or the build fails. There is no hand-spelling to protect and no author's ear to please; the namer's will has nowhere left to intervene between the lemma and the token it becomes.

That is bitul applied to language-craft rather than to prayer: not the absence of a self, but a self that has agreed to stop asserting itself where a rule is meant to govern instead. The dialect's own name, עלוקווענטיא (eloquentia, "a speaking-out"), was one candidate among several built the same mechanical way, screened afterward — along with the rest — for its gematria, and found alone among them to land, under both standard and expanded counting, on 358: the value of משיח. No one chose its letters to reach that number; the transliteration table fixed them, the same way it fixes every token here, and 358 is simply what they summed to. The tradition calls a coincidence like this a remez, not a proof, and is right to. It sits well, though, beside a name for "speaking-out" landing on the value of the sefirah said to hold nothing of its own — Malchut, the mouth — whose whole work is to take what it is given and speak it faithfully outward.

The dialect is Hebrew end to end: a Latin lexicon carried in traditional Hebrew script, on the Yiddish and Ladino model. Verbs are the Latin perfect, first person singular (verificavi, custodivi, scripsi — the same voice as Hebrew's own -תי); objects are Latin nouns; statuses are perfect passive participles. Prose stays Hebrew; tokens are dialect. The LLM reads the protocol and converses with the user in the user's own language — that boundary, and only that boundary, is where English belongs.

Orthography: plene, no nikud; qu→קוו, ph→פ, th→ט, ch→ק, sh→ש, ae/oe→ע, x→קס, f/p→פ, c/k/q→ק, i/j/y→י, o/u→ו, v/w→וו; doubled letters collapse; word-initial i/o/u take א; an א separates וו from a vowel ו; final forms on the last letter. Every letter in every token traces back through this table to the Latin letter that produced it, and every token can be regenerated from nothing but its lemma and this table — not as a devotional claim, but as the property the test suite checks on every run.

Kernel verbs

עלוקווענטיא Latin מה הפועל עושה
פערקוסי percussi טבעתי: יצרתי לחש, קמע, שומר או שילוב בספר
רעקענסוי recensui סקרתי: קטלוג הספר
דיקסי dixi דיברתי: הטלתי לחש
דירעקסי direxi ניתבתי: דירוג שמות לכוונה
אינקאנטאווי incantavi קסמתי: קשירה או הסרה של קמע
קוסטודיווי custodivi שמרתי: מצב, נעילה, שחרור ובדיקה של שומר
קוניונקסי coniunxi שילבתי: צינורות חתומים
רעפעטיווי repetivi נזכרתי: אחזור נוהל שמור
עקסטולי extuli העליתי: מעקבים חוזרים לנוהל
סקריפסי scripsi רשמתי: אימות הפנקס
סיגנאווי signavi חתמתי: פנקס ההטלות
מעמוראווי memoravi תיעדתי: רישום מעקב
דעקרעווי decrevi הכרעתי: בחירת נוהל לכוונה
קוקורי cucurri הרצתי: ביצוע נוהל
פרוקעסי processi המשכתי: הצעד הבא
ענומעראווי enumeravi מניתי: רשימת נהלים
אפרובאווי approbavi אישרתי: אישור נוהל
סטאטוי statui קבעתי: מדיניות קידום
מענסוראווי mensuravi מדדתי: מדדי הזיכרון
עקסערקוי exercui תרגלתי: תרחיש סינתטי
דעקלאראווי declaravi הצהרתי: חוזה האירועים
אינסטיטוי institui הגדרתי ושילבתי מארח לפי חוזה מפורש
קונסולטאווי consultavi בחנתי מעטפת קבלה מקומית כנסוי תפקודי

hakodesh --help lists the canonical command forms under lexicon. The traditional-Hebrew twins of 0.3/0.4 (טבעתי, שמרתי, ...) and the English names still dispatch as silent legacy aliases through 0.5.x and are removed in 0.6.0. All spellings are reserved: mint refuses them as a whole artifact name.

Status vocabulary

Closed and declared by protocol: פערמיסום (permissum), קומפלעטום (completum), נעגאטום (negatum), דעפעקטום (defectum), קלאוסום (clausum), פרעוויסום (praevisum), אינקעפטום (inceptum), סינקרונאטום (synchronatum), אפערטום (apertum), וועריפיקאטום (verificatum), and the rest in dialectus.STATUS. Event kinds, notification policies, severities, actor roles, trace sources, outcomes, correctness, procedure statuses and decisions are written in the dialect and read in either spelling within hakodesh.event/v1; the published descriptor lists both. JSON keys stay English until the v2 schema bump (0.6.0).

Errors

Every kernel error carries a stable error_code (ward.unknown, mint.reserved, ...) and Hebrew prose. Tests assert on codes, never on prose. Artifact names may be lowercase Latin or Hebrew, digits and dashes; every lookup normalizes to NFC.

hakodesh רעקענסוי                                      # empty-book inventory
hakodesh פערקוסי פרובאווי-קאנון --confirm              # mint a dialect-named spell
hakodesh דיקסי פרובאווי-קאנון                          # cast it; receipts land in receipts/פרובאווי-קאנון/
hakodesh אינסטיטוי claude preview                      # inspect supported Claude setup diff
hakodesh אינסטיטוי claude apply --confirm              # explicit first activation
hakodesh אינסטיטוי claude check                        # inspect installed adapter version

Development

python -m pip install -e ".[dev]"
python -m pytest                 # unit, property and tripwire tests
python -m build                  # wheel + sdist into dist/

The package runtime depends on platformdirs. Its Claude adapter is bundled in the wheel and uses the configured Claude Code settings home; it does not inspect a vault or move secrets. tests/test_agnostic.py keeps the rest of the package host-neutral.

SDK

See docs/ONBOARDING.md for the update/setup journey, copy-ready AGENTS.md and CLAUDE.md blocks, safety coverage, rollback, and trust boundary.

from hakodesh.catalog import catalog
from hakodesh.mint import mint
from hakodesh import events, akashic, grimoire
from hakodesh.enchant import bind, lift
from hakodesh.ward import unlock
from hakodesh.combo import seal, cast

Book law

The book is per user, under HAKODESH_HOME. A fresh install has zero spells, enchantments, wards or combos, and nothing is intrinsic: discovery picks up a file the moment it lands under HAKODESH_HOME/book/. The repository's workshop/ is a book as source: mint from it with --from; it is not in the wheel and never lands in a book by itself (docs/PROTOCOL.md, §Book law).

Metadata

Release files for hakodesh 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hakodesh 0.8.1
File Size Uploaded Provenance Actions
hakodesh-0.8.1.tar.gz 444.8 kB Without provenance Details for hakodesh-0.8.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hakodesh 0.8.1
File Interpreter ABI Platform Actions
hakodesh-0.8.1-py3-none-any.whl Python 3 none any Details for hakodesh-0.8.1-py3-none-any.whl

Total release size: 645.6 kB

Release files / hakodesh-0.8.1.tar.gz

Download URL hakodesh-0.8.1.tar.gz
Size 444.8 kB
Tags Source
SHA-256 checksum
How to use checksums
1dd57fc122096f0be5b78b59eaa5feffe9058eaeb31a4e853967b5e3b54ea25e
BLAKE2b-256 checksum
How to use checksums
94bc90db1d4711058613b05287a68cada292adef440470e37fee21418775cd5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / hakodesh-0.8.1-py3-none-any.whl

Download URL hakodesh-0.8.1-py3-none-any.whl
Size 200.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
53e3ec50c492294a34bb1f69685e59c27144a013fe55e50f9e50f0829d3bf96a
BLAKE2b-256 checksum
How to use checksums
f396fa13d867c70b2169c4003cb7ebaa916d513b2d31d2ae4741d3c2a348dbf6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for hakodesh 0.8.1

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A 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.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page