Quickstart
Install, configure one provider, and send your first message in under 10 minutes.
Welcome to Kazma
Kazma (كاظمه) is a multi-platform, autonomous AI agent framework built on a LangGraph supervisor brain, swarm orchestration, cross-platform dispatch (Telegram / Discord / Slack / Web / TUI), and an OpenAI-compatible LLM provider layer — with first-class Arabic / RTL support and a Gulf-cultural conversational protocol (Majlis).
As of v0.11.0 (Hands), Kazma is the self-hosted agent that can edit your repo, message your team, and schedule your life — and that will stop, ask, or fail honestly rather than invent an answer. Chat is home (/ → /chat). file_apply_patch_set is one HITL card (optional pytest verify). Web /ide is CodeMirror 5. kazma acp is the industrial editor loop. It still includes a transport-agnostic IDE, per-turn RAG retrieval with pluggable embeddings (sqlite-vec locally, pgvector with Postgres), an encrypted secret vault, auto-scaling swarm workers, dual-backend persistence (SQLite by default, optional Postgres for SaaS), a Task Ledger for durable intent resolution, Turn Delivery V2 (journaled, resumable streams across tabs and reconnects), an official-API X publisher with an append-only audit log, and production hard-gates (KAZMA_PRODUCTION, YOLO block, git-write always-gate, default-deny API auth, opaque web sessions).
These docs are a ground-up, code-verified reference: every factual claim is traceable to source, and anything not yet implemented is explicitly marked.
Source of truth: product docs also live in the monorepo under
docs/docs/(Docusaurus). This marketing site mirrors operator-facing guides; prefer the monorepo for the latest ops runbooks (WSL fixed access, Postgres cutover, DR).
Architecture
The supervisor ReAct loop, IDE subsystem, data-flow diagrams, and subsystem internals.
Configuration
Every kazma.yaml key, every env var, and the ConfigStore override model.
Security & Safety
The three HITL gates, production hard-gates, YOLO policy, and fail-closed behavior.
Knowledge Base & Soul Store
Vector memory (Chroma), per-turn RAG retrieval, and prompt-fenced Soul Store self-improvement.
Time Travel & Replay
State snapshot recording (snapshots.db), thread rewinding (/replay), and branching (/fork).
IDE Subsystem
Transport-agnostic coding engine, ContextVar workspace scoping, and environment awareness.
Swarm Orchestration
Six patterns, auto-routing, auto-scaling workers, and the reliability layer.
Gmail & Microsoft — OAuth, IMAP, or POP — plus a zero-config sandbox mailbox.
Task Ledger
Durable task state: “next” resolves against the ledger, never the transcript; git writes always gate.
X Publisher
Official X API v2. Compose and plan in X Studio (/x). Chat tools stay always-HITL; the Web click is the approval.
Document Intelligence
Ingest, parse, OCR, index, generate, and redact documents through an isolated pipeline.
Products
Web UI, TUI, IDE, Command Center / Swarm, and multi-user SaaS operator surfaces.
Where to go next
Section titled “Where to go next”- New to Kazma? Start with the Quickstart.
- Evaluating for production? Read Architecture, then Security & Safety, Deployment, and the Production checklist.
- Operating a running instance? Jump to Troubleshooting, Slash commands, and the CLI reference.
- Postgres / multi-user? See Multi-user SaaS and Deployment → Postgres & SaaS.
- Documents? Document Intelligence · Phases · Rendering.
- What’s new? Recent features.
- Posting on X? X publisher — X Studio (
/x) vs Scheduled (/scheduled).
What’s new (2026-09-10) — Hands 0.11
Section titled “What’s new (2026-09-10) — Hands 0.11”| Area | Change |
|---|---|
| Chat is home | GET / redirects to /chat. First-run asks for one provider key and one model. Inspectors live under More. |
| Hands coding loop | file_apply_patch_set is one HITL card (-/+ hunks). verify=true runs nearby pytest. Supervisor re-hops on TESTS FAILED (cap 3). |
Web /ide | CodeMirror 5 fromTextArea (nord). Textarea-first so a blocked CDN still shows the file. Monaco is gone. Read-only git is not HITL. |
| ACP daily driver | kazma acp sends structured diffs; session/cancel aborts the turn. Zed agent_servers snippet in the CLI reference. |
| Jail | KAZMA_CODE_EXEC_DOCKER=force blocks host shell_exec unless KAZMA_HOST_SHELL=1. |
What’s new (2026-09-03)
Section titled “What’s new (2026-09-03)”| Area | Change |
|---|---|
| Live Task Card | One merged turn-state surface in the chat: live phase label, elapsed time, step count, and the watchdog countdown — with approval cards rendered inline in the transcript. Claimed cards park above the streamed reply and collapse to a one-line bar with the decision chip. |
| HITL Gate Registry | hitl_gates.db is the only decision author: one card, one row; a second Approve gets 409. Watchdog auto-deny dual-writes the gate, so an unanswered card settles deterministically instead of hanging the turn. Approval cards count down to the auto-deny deadline. |
| Turn Delivery V2 | The chat journal is the source of truth; close_turn is the only closer; the client projects. Ghost/phantom approval cards, duplicate bubbles, and CoT auto-expands were fixed by the same cutover. |
| Security audit waves 0–8 | SSRF pin-IP on direct scraping (private peers abort), login-password PBKDF2 aligned with the vault (600k), tenant-scoped proposals, FanOut tri-state HITL, peer abort, and a hardened fail-closed gate registry. Exec summary in the monorepo. |
| Diagnosis map (new page) | A symptom → element → invariant map for Kazma’s multi-path systems (chat/HITL/memory/swarm): what is the same element, how many paths serve it, where to look first. See Diagnosis map. |
What’s new (2026-08-31)
Section titled “What’s new (2026-08-31)”| Area | Change |
|---|---|
| X Studio | First-class /x composer + X-only planner: Post now, Schedule, reschedule, thread hops, delete a live tweet, load a saved draft (proposal_id — stored text wins). Chat x_post stays always-HITL. All clocks opens /scheduled (cron + X). |
| Brand type + mark | IBM Plex Sans / IBM Plex Sans Arabic across the Web UI, these docs, and generated documents. Letterhead K is logo, favicon, and avatar. Amiri remains the naskh fallback. |
Guard --reload | Deploy kills are not treated as crashes, so the fifth reload of the day is not a 300s wait. Restart KazmaAgent once if an old guard is still climbing. |
What’s new in 0.10.0 (summary)
Section titled “What’s new in 0.10.0 (summary)”| Area | Change |
|---|---|
| Task Ledger | Durable per-conversation task state (SQLite): “proceed / next / كمّل” resolves against the ledger, never the transcript. Unresolved continuations can only produce one clarifying question (tools removed for that turn). |
| Git-write always-gate | git commit/push/merge/… always require an approval card on every execution path — YOLO cannot auto-approve repo mutations. YOLO windows default to 1h (was 4h). |
| Turn Delivery V2 | Journaled id-lined stream frames + broker: cursor resume after reconnect, multi-tab live parity, hidden-tab title badge, Web Push for discarded tabs. |
| Transcript recall fallback | When V2 memory recall returns nothing, past chat sessions are searched automatically and injected as a fenced untrusted block. KAZMA_TRANSCRIPT_RECALL=0 to disable. |
| X Publisher | Official X API v2 only (OAuth 1.0a, vaulted keys). Chat always-HITL; Web X Studio click is the approval. ToU caps + append-only audit DB (x_audit.db). |
| Streaming UI hardening | Pin-to-bottom scrolling, steady status strip, formatted streaming with rich user bubbles, no markdown double-paint flicker; cancelled turns keep their full narration. |
| Memory audit fixes | Ego-graph hub anchoring, tenant-scoped graph-clear, mirror tombstone propagation + reconcile_memory_mirror.py, FTS drift rebuild, merge-ledger archive. |
| pgvector auto-select | Dense memory recall auto-uses pgvector when a Postgres DSN is present (KAZMA_PGVECTOR=0 keeps sqlite-vec). |
What’s new in 0.6.x (summary)
Section titled “What’s new in 0.6.x (summary)”| Area | Change |
|---|---|
| Default port | kazma serve binds 127.0.0.1:9090 (was 8000). Docker maps host 9090 → container 8000. |
| Postgres | Optional KAZMA_DATABASE_URL + [postgres] extra for ConfigStore, chat sessions, swarm tasks, and LangGraph checkpoints. |
| Production | KAZMA_PRODUCTION=1 hardens YOLO, code_exec Docker, vault key, workspace root, MCP untrusted tools. |
| Auth | Default-deny /api/*; opaque kazma-session cookies; optional OIDC + platform RBAC. |
| UI | SVG icon system (no emoji chrome); mobile bottom-nav spacing; dashboard shows Postgres backend when active. |
| Docs monorepo | Single Docusaurus tree under docs/; legacy dual trees archived. |
Native email-manager: sandbox, Gmail OAuth/IMAP/POP, Microsoft Graph OAuth/IMAP/POP; Settings → Email; HITL on send/delete/categorize. | |
| Web research | Chat tools: read_url paging, crawl_site, workspace digests — no separate /research slash command. |
The legacy of the name
Section titled “The legacy of the name”Kazma (كاظمة) was an ancient coastal oasis in Kuwait — a network of wells and a gateway for trade between civilizations. It was also the site of the legendary Battle of Chains (ذات السلاسل, 633 CE): the Persian army chained its soldiers into a single, rigid wall, yet Khalid ibn al-Walid shattered it through precise, decentralized maneuvering — and won.
The framework inherits those same pillars — not as metaphor, but as architecture. Described honestly, as the code implements them today:
- The Wells → Memory. Long-term vector memory (Chroma) with optional per-turn retrieval, plus explicit
memory_search/memory_storetools. (See Memory & RAG.) - The Gateway → Routing. A single LangGraph supervisor routed out to many channels — Telegram, Discord, Slack, Web, and the TUI — through one adapter layer. (See Gateways & Platforms.)
- Breaking the Chains → Resilience. The chains in that battle were rigidity — and rigidity is what makes monolithic agent pipelines fragile. Instead Kazma runs decentralized swarm patterns and self-healing circuit breakers, adapting and recovering where rigid chains would snap. (See Swarm Orchestration and Security & Safety.)
Documentation honesty: Kazma distinguishes what the code does today from what older copy claims. Features that are only partially wired are flagged inline under “Honest status notes” — most notably in Memory & RAG and Troubleshooting.