Development Setup
Development Setup
Section titled “Development Setup”Prerequisites
Section titled “Prerequisites”- Python 3.11.5+ (soupsieve 4, which closes three 2026 advisories, needs it)
- Node.js 18+ (for docs)
- Git
Clone and install
Section titled “Clone and install”git clone https://github.com/Mubder/kazma.gitcd kazma
# Create virtual environmentpython -m venv .venvActivate the venv for your platform:
# Linux / macOS / WSLsource .venv/bin/activate# Windows (PowerShell).venv\Scripts\Activate.ps1:: Windows (CMD).venv\Scripts\activate.bat# A lighter set, by hand (rag + tests + TUI); setup.sh / setup.ps1 install Express, Full or Custom.# There is no [cli] extra — kazma-cli is in the wheel.pip install -e ".[rag,dev,tui]"# or: uv sync --inexact --extra rag --extra dev --extra tui --extra postgresuv sync here is for a first install into a fresh environment. On an
installed Kazma, update with python -m kazma_cli update instead: a bare
uv sync removes every package outside the extras it names
(Kazma update).
Activate the git hooks
Section titled “Activate the git hooks”pre-commit comes with the dev extra, but the hooks do nothing until you
install them into your clone — do this once, per clone:
pre-commit installEvery commit then runs two AST-only gates (~8s, no app boot):
- import gates — every product module still imports, and no
kazma_*import reference dangles after a file is moved or deleted. - static gates — no blocking DB call inside
async def, no fire-and-forgetasyncio.create_task, every registered tool carries a HITL tier, and web-tool output is fenced as untrusted.
Run them against the whole tree at any time:
pre-commit run --all-filesBoth hooks go through scripts/run_gates.py, which finds the project
virtualenv itself. pre-commit sanitises PATH for system hooks, so a
bare python in the hook entry would resolve to pre-commit’s interpreter
(no pytest), and a relative .venv/Scripts/python.exe fails on Windows —
which is why these hooks silently never ran there before 2026-08-29. If your
virtualenv lives somewhere unusual, point the shim at it:
export KAZMA_GATE_PYTHON=/path/to/pythonProject structure
Section titled “Project structure”kazma/ kazma-core/ Agent, LLM providers, swarm, V2 memory, IDE kazma-gateway/ Telegram / Discord / Slack kazma-ui/ FastAPI dashboard + Settings kazma-tui/ Textual dashboard kazma-cli/ `kazma` CLI kazma-skills/ Native skills docs/ Docusaurus site tests/ Cross-cutting testsRun tests
Section titled “Run tests”pytestpytest --cov=kazma_corepytest tests/test_checkpoint.pyLinting
Section titled “Linting”ruff check .ruff format .mypy kazma-core/Documentation
Section titled “Documentation”cd docsnpm installnpm run start # local dev servernpm run build # production buildThe site’s build packages are kept by npm audit fix (never --force) and
docs/package-lock.json. package.json names Mermaid’s major version
(overrides, Mermaid 12 since 2026-11-13, with the KaTeX 0.18 that fixes
Mermaid 11’s KaTeX advisory): every diagram in the docs must parse with it
(tests/test_docs_mermaid_diagrams_parse.py, which needs npm install here
and Playwright’s Chromium). It also holds uuid on 11.x for the dev server’s
sockjs, which asks for 8.x and whose advisory every Docusaurus package
inherited, and tinypool on 2.x and serialize-javascript on
7.x (2026-11-11): Docusaurus 3.10.2 (the newest) holds both a major version
back, and their critical and high advisories are fixed only there. The site
builds with both (npm run build), which needs Node 20, as Docusaurus does.
Do not run npm audit fix without checking npm ls @docusaurus/preset-classic
after it: on 2026-11-11 it moved the preset back to 3.7.0, a second, older
Docusaurus beside 3.10.2. What the audit still reports is low and has no
fixed release yet (deepmerge, in the SVG plugin’s
build-time configuration merge).

