IDE
Kazma’s IDE is a transport-agnostic coding backend: one service for Web, TUI, chat /ide commands, and the in-process CLI (kazma ask / kazma acp). Mutations always go through LocalToolRegistry so HITL cannot be bypassed.
محرّر الويب (Hands 0.11): CodeMirror 5 fromTextArea على /ide (سمة nord،
--bg-deep). تُكتب بايتات الملف في <textarea> أولًا ثم يغلّفها CodeMirror
لأرقام الأسطر والتلوين. إن حُجب الـ CDN يبقى الملف ظاهرًا كنص. Monaco لم يعد
مستخدمًا. تعديلات الوكيل على ملفات موجودة يجب أن تستخدم file_apply_patch
أو file_apply_patch_set لا file_write كامل الملف.
Codebase index: codebase_search (and GET /api/ide/codebase?q=) finds
definitions via a per-workspace SQLite symbol index (tree-sitter if you
pip install 'kazma[index]', else regex) plus live ripgrep. Install rg
for faster text hits. Kill-switch KAZMA_CODE_INDEX=0.
الذكاء اللغوي: محرّر الويب تلوين صياغة فقط (أوضاع CodeMirror).
POST /api/ide/lsp ما زال موجودًا لكن غير مربوط في واجهة CodeMirror.
Kill-switch KAZMA_IDE_LSP=0. لمسار محرّر صناعي استخدم kazma acp في Zed.
Components
Section titled “Components”| Piece | Module |
|---|---|
| Service | kazma_core/ide/service.py |
| Env context injection | ide/env_context.py |
| Per-task workspace | ide/workspace_scope.py |
| Web API | kazma_ui/ide_api.py + /ide page |
| TUI | kazma_tui editor screen |
| Chat | Gateway /ide slash commands |
Workspace resolution (must stay consistent)
Section titled “Workspace resolution (must stay consistent)”Both file_write._get_workspace() and IdeService._resolve_workspace_root() use:
- Per-task
workspace_scopeContextVar configure_workspace()globalKAZMA_WORKSPACEenv- Active WorkspaceStore row
- Default
cwd/kazma-data/workspace
Production may require an explicit workspace root. Path traversal is blocked with normpath + containment checks.
Path grants (outside-workspace access)
Section titled “Path grants (outside-workspace access)”Access outside the active workspace is denied by default, but can be opened
with permission. Source of truth: kazma_core/workspace/path_policy.py +
workspace/path_grants.py, wired through IdeService.resolve, file_read /
file_write, file list/search/delete/append, and the shell path checks.
| How | Effect |
|---|---|
| Chat (smooth) | When a file tool fails on an outside-workspace path, the agent calls request_path_access (a danger-tier HITL card). On approval a session grant (~1h TTL) is created and the tool retries. |
| Settings / API | Durable extra roots via workspace.extra_roots + GET/PUT /api/workspace/extra_roots (path, mode: read | write, label). Persist until removed. |
Read grants never allow writes. Denial messages tell the agent how to request a grant, so the loop is smooth rather than a hard failure.
Operations
Section titled “Operations”| Action | HITL | Notes |
|---|---|---|
| Read / list / search | Usually safe | Workspace-scoped |
| Codebase search | Safe | codebase_search / GET /api/ide/codebase — symbols + ripgrep |
| Language intelligence | Safe | خلفية /api/ide/lsp موجودة؛ محرّر الويب CodeMirror تلوين فقط |
| Write / delete | Danger tools | Graph or bus approval |
| Apply patch | Danger (file_apply_patch / file_apply_patch_set) | Search-replace or unified diff; بطاقة HITL واحدة للمجموعة |
| Run / run_file / shell | Danger | shell_exec / python_exec؛ force يمنع شِل المضيف إلا مع KAZMA_HOST_SHELL=1 |
| Git status / diff / log | Safe | git للقراءة عملية فرعية في مساحة العمل (ليست HITL) |
| Git commit / push / clean | Danger | Native git skill tools |
| Send to swarm | — | Attaches env context for workers |
AI chat from IDE
Section titled “AI chat from IDE”File-aware chat reuses /api/chat/stream (no parallel agent path). Env context is injected so the model sees branch, repo, and available tools.