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.

PyPI name, import, and command: hakodesh. Not snax. Not snx.

Install

pip install hakodesh

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

Kernel commands

These are the runtime, not starter spells:

--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 until you mint and bind an enchantment.

Hebrew-native names

Artifact names may be lowercase Latin or Hebrew (U+0590–U+05FF), digits and dashes. Every lookup normalizes to NFC, so a presentation-form or decomposed spelling typed at the shell matches the stored name. Kernel verbs have Hebrew equivalents via hakodesh.lexicon (devra קטלגתי == devra catalog; טבעתי is a third entry point for mint).

טבעתי mint בדקתי-קנוני --confirm      # mint a Hebrew-named spell -> book/spells/בדקתי_קנוני.py
devra בדקתי-קנוני                      # cast it; receipts land in receipts/בדקתי-קנוני/

Wards are fail-closed: ward check on an unknown or unreadable ward denies. Ward lookup reads book/wards/*.json directly and never executes spell modules, so a broken spell cannot disable a ward. A spell that fails to import is reported under catalog()["broken"] instead of taking the book down.

Canonical repo on Google Drive

The source of truth is a bare repo in the Drive folder GitMirrors/hakodesh.git (id 1scHceC8Q43y1wDFyoWenQNjb3RAWbGVi), moved with rclone — never through the Drive FileProvider mount, which hangs on file reads. Local checkouts are transient.

scripts/drive-sync.sh down ~/hakodesh-work   # rclone bare repo -> ~/.cache/hakodesh-sync/canon.git, clone it
# work, commit on main
scripts/drive-sync.sh up   ~/hakodesh-work   # push -> local bare, gc, upload objects first, packed-refs last, verify
rm -rf ~/hakodesh-work                        # nothing canonical lives on the workstation

The Drive layout is packed-refs plus a loose refs/heads/main with the same sha (git needs refs/ to exist and rclone never creates empty directories); the script writes both from one sha and uploads the loose ref last. Release order: push to Drive, then python -m build && twine upload, so devra בדקתי-קנוני --accept can record the head the published wheel came from.

SDK

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

Empty book law

A fresh install has zero user spells, enchantments, wards, or combos. Discovery picks up a file the moment it lands under HAKODESH_HOME/book/.