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.
Web editor (Hands 0.11): CodeMirror 5 fromTextArea on /ide (nord
theme, --bg-deep). File bytes are written into a <textarea> first, then
CodeMirror wraps it for line numbers and syntax. If the CDN is blocked, the
file is still visible as plain text. Monaco+Alpine was a dead end (browser
hang / empty tabs) and is gone. Agent edits to existing files should use
file_apply_patch or file_apply_patch_set (unique
old_string/new_string or a unified diff), not a whole-file 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 -e ".[index]", else regex) plus live ripgrep. Install rg
for faster text hits. Kill-switch KAZMA_CODE_INDEX=0.
What a search reads: in a git repository, the index and the agent’s
file_search read the files the repository keeps: tracked files, plus
untracked ones .gitignore does not exclude. An ignored folder (a cloned
repository, build output) is left out unless you name it as the path to
search. A folder outside any repository is walked. Either way, environments,
caches, build output and Kazma’s data folder are skipped.
Language intelligence: the Web editor is syntax-only (CodeMirror
modes). POST /api/ide/lsp still exists for hover/complete/definition/
diagnostics (Python/JSON in-process; symbols reuse the code index) but is
not bound in the CodeMirror UI. Kill-switch KAZMA_IDE_LSP=0. For an
industrial editor loop, use kazma acp in Zed.
Components
Section titled “Components”Git status, history and diff reads use an explicit option policy and do not require an approval card. Output-file options and outside-workspace operands are refused before spawning Git. Reads disable fsmonitor, external diff, textconv and checkout-filter helpers and preserve operator newline configuration. Unsupported read options produce an error rather than falling through to shell execution. Branch creation and other mutations use the existing tool-registry approval path. The working tree is pinned to the active workspace, including when local Git configuration names a different folder.
Reads also disable automatic fetching of missing objects from partial-clone
remotes, which could otherwise run configured remote helpers. A missing object
returns an error; fetch it through approved terminal execution before retrying.
The installed Git must support --no-lazy-fetch; older Git refuses reads with
an upgrade hint. This requirement is checked by Git itself on every read.
Repositories using custom checkout filters are compared without those conversions, so raw-file differences may appear. Use an approved terminal command when the repository’s custom transformations are required.
| 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)”Every file tool, the IDE service, the workspace API and the environment block
ask one function, kazma_core.workspace.binding.resolve_active_root()
(file_write._get_workspace() is its compatibility name):
- Per-task
workspace_scopeContextVar (a swarm task aimed at one repository) - Active WorkspaceStore row (what Switch Repo or a clone chose)
- The process pin from
configure_workspace() KAZMA_WORKSPACEenv- Default sandbox:
<data dir>/workspace
A relative path given to an agent tool means this folder, never the server
process’s working directory (binding.resolve_tool_path). Production requires
an explicit workspace policy: administrator-configured security.workspace_roots
or KAZMA_WORKSPACE_ROOT. Selecting, creating or switching a workspace refuses
paths outside the resolved roots, including symlinks. When the environment root
is also set, a stored policy cannot expand it. 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. |
| Workspace page / API | Workspace → Folders outside the workspace: durable extra roots (workspace.extra_roots, GET/PUT /api/workspace/extra-roots: path, mode: read | write, label), listed, added and removed there. A new root must be a full path to an existing folder, not a whole drive, and not one holding Kazma’s own install or data. 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 backend exists; Web editor is syntax-only CodeMirror |
| Write / delete | Danger tools | Graph or bus approval |
| Apply patch | Danger (file_apply_patch / file_apply_patch_set) | Search-replace or unified diff; one HITL card for a set; same HITL as write |
| Review / reject a patch | Restores from the checkpoint | The review lists each file changed since the checkpoint taken before the patch, a file created since included. Rejecting a hunk or a whole file restores it from that checkpoint: only a file the checkpoint holds, within the paths the tools may write, keeping its own line endings (/api/ide/checkpoints/*) |
| Run / run_file / shell | Danger | shell_exec / python_exec policy; Docker force blocks host shell unless KAZMA_HOST_SHELL=1 |
| Git status / diff / log | Safe | Read-only git is a workspace subprocess (not HITL shell_exec) |
| 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.