Zelari Code

             -#%=
           .*%%%@#:
          =%%%%%%%@*
         +%%%%%%%%%%#.
        +%%%@@@@@@@%@#.
      .*%@@@@@@@@@@@@@%-
     .#%@@@@@@@@@@@@@@@@-
     *%@@@@@@@@@@@@@@@@@%.
    :@%%@@@@@@%:+%@@@@@%@=
     =@%%@@@@@%.=-+%@%%@*
     .=@@%@@@@%.*@*-+@@*.
   -*%@@@@@@@@%.*@@@+:#@@#=.
  *%%%%%%@@@@@@.*#%#=-:+@@@%
 :@%%%%%%@@@@@@.:=.*:*@@@@@@=
 *@%%@%%@@@@@@@*%@*:-:%@@@@@%.
:@@@%@@@@@@@@@@@@@@#%@@@@@@@@=
*%%%%%%%%%%%%%%%%%%%%%%%%%%%%#

     Z E L A R I   C O D E
        Anathema Studio

AI Council coding agent CLI — multi-agent orchestration with slash commands, provider-agnostic LLM streaming, and self-update.

By Anathema Studio · Product page · GitHub · npm · Contributing · Security

Trailer (EN, ~30s): docs/media/trailer/zelari-code-trailer.mp4 · media kit

📖 Full user guide (IT) — install, TUI, slash commands, council, skills, workspace, headless, MCP, Desktop.

Zelari Code is an open-source AI council coding agent for the terminal: a multi-agent pipeline (Caronte, Nettuno, Gerione, Plutone, Minosse, Lucifero), a kraken super-agent (default; aliases agent/single) that can spawn explore/general/verify tentacles, and optional zelari missions that loop until a deliverable is done. It ships a rich TUI (Ink + React), slash commands, plan/build phases, and provider-agnostic LLM streaming (OpenAI-compatible, xAI Grok, ChatGPT, Anthropic, GLM/Z.AI, MiniMax, DeepSeek). OAuth via /login grok, /login chatgpt, /login anthropic. The reusable runtime is published as @zelari/core (Apache-2.0).

npm install -g zelari-code
zelari-code

Prerequisites

| Requirement | Version | Notes | |---|---|---| | Node.js | ≥ 24 LTS | CI tests Node 24 only; Node 20 was dropped from the matrix (the dependency tree requires it). | | npm | ≥ 11.7 | Required to reproduce the workspace lockfile; use the version pinned by packageManager. | | OS | Linux, macOS, Windows 10/11 | Tested on Pop!_OS 24.04, macOS 15, Windows 11. Windows requires Git Bash (auto-detected). | | Disk | ~50 MB for the CLI + @zelari/core | Models are not bundled — provider APIs are remote. | | Account + API key | 1 of: xAI Grok, ChatGPT, Anthropic, OpenAI-compatible, GLM/Z.AI, MiniMax, DeepSeek | OAuth via /login grok, /login chatgpt, /login anthropic. |

Optional (advanced tools)

These are opt-in — the CLI runs fine without them. The agent auto-skips a tool if its dependency is missing.

| Tool group | Dependency | Used by | |---|---|---| | lsp_* | Language server on PATH (e.g. typescript-language-server, pyright-langserver) + Node/Python LSP client libs | lsp_definition, lsp_references, lsp_hover, lsp_symbols, lsp_rename | | ast_* | (none) | ast_outline, ast_find_symbol — TypeScript Compiler API, no LSP needed | | semantic_search | Local embedding model (default Xenova/all-MiniLM-L6-v2 via @xenova/transformers, downloads on first use) | semantic_search, /index | | browser_check | Playwright (npx playwright install chromium once, ~150 MB) | browser_check | | diagnostics loop | eslint and/or ruff on PATH (project-local preferred) | post-edit compile/lint feedback |

Disable any tool group: set ZELARI_LSP=0, ZELARI_AST=0, ZELARI_SEMANTIC=0, ZELARI_BROWSER=0, ZELARI_DIAGNOSTICS=0.

Install

If you already ran npm install -g zelari-code above, skip to First Run.

npm install -g zelari-code
zelari-code --doctor   # recommended once on Windows

Optional: Zelari Desktop (Tauri)

An installable GUI shell lives in apps/desktop/. It does not replace the CLI — it streams zelari-code --headless into a modern chat UI. GitHub Releases attach platform installers on each v* tag.

Installer ≠ CLI. Downloading Desktop from GitHub does not install or upgrade the global zelari-code package. Use npm i -g zelari-code (or Desktop → Settings → Update CLI). First launch shows a Setup guide when Node/CLI is missing.

Desktop highlights: Mode / Phase / Provider bar · Files|Git project panel · Settings (provider keys, App updates, Update CLI, MCP Extensions, SSH Connections) · multi-turn chat history · optional overlay HUD · password/agent/key SSH targets (ssh_status / ssh_run).

npm run build                 # CLI side-car
npm run desktop:install
npm run desktop:dev           # Tauri dev window
# npm run desktop:build       # MSI / NSIS / DMG / AppImage

See apps/desktop/README.md and docs/GUIDA.md (Desktop, MCP, SSH). Requires Rust + Node ≥ 24.

Prerequisites:

• Node.js ≥ 24 — required. Without it the agent cannot run npm/tsc/builds, so zelari-code refuses to boot.
• Git — recommended. Without it, /diff, /undo and the git sidebar are disabled. Install from https://git-scm.com.
• Git Bash (Windows only) — recommended. The agent's bash tool needs real POSIX semantics (ls, which, $VAR, &&). Ships with Git for Windows.

After install, verify your environment:

zelari-code --doctor   # checks shim, bundle, PATH, node/git/bash in the agent shell

Why --doctor matters on Windows: the agent runs commands through Git Bash, which inherits a different PATH than the Node process. Node can be visible to PowerShell yet invisible to Git Bash (typical when Node was installed for "current user" only). --doctor's node (agent shell) row catches this; the boot-time preflight (runPreflight) blocks the launch with an actionable message instead of letting the agent fail mid-task.

zelari-code: command not found (Windows)

After npm install -g, the zelari-code command may not be on your PATH. Fix:

PowerShell (run as admin, then restart your terminal):

$npmPrefix = npm config get prefix
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$npmPrefix", "User")

Git Bash / WSL:

echo 'export PATH="$(npm config get prefix):$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify the fix: where zelari-code (CMD) or which zelari-code (Bash) should print a path.

Node visible to PowerShell but not to Git Bash? This is the dual-PATH problem: Node installed for "current user" only reaches the user shell, while Git Bash inherits the system Path. Fix: reinstall Node with "Add to PATH for all users", or add C:\Program Files\nodejs\ to the System Path (not User). Confirm with zelari-code --doctor — the node (agent shell) row must read OK.

First Run

The first time you run zelari-code (or whenever your provider config is missing), the CLI launches a 5-step onboarding wizard instead of the regular TUI:

╭─────────────────────────────────────────────────╮
│ zelari-code — first-time setup                  │
│ 1/welcome  2/provider  3/model  4/apikey  5/...│
│                                                 │
│ Welcome! Let's get you coding in under 2 min.   │
│ Press [Enter] to continue, [Q] to quit.         │
╰─────────────────────────────────────────────────╯

The wizard walks you through:

1. Welcome — overview + how to quit.
2. Provider — pick from grok, minimax, glm, deepseek, openai-compatible (↑/↓ + Enter).
3. Model — type a model name or accept the default (Enter).
4. API key — choose env (use GROK_API_KEY etc.), keystore (save locally), or skip (set later via /login).
5. Confirm — review + Enter to commit.

When you press Enter on confirm, the wizard writes ~/.tmp/zelari-code/provider.json (and keys.json if you chose keystore), shows a brief "✓ Setup complete!" banner, then transparently transitions into the regular TUI — no need to re-launch.

Skipping / re-running

zelari-code --no-wizard            # skip wizard even on first run
zelari-code --reset-config         # force re-run wizard (clears provider.json)
ZELARI_NO_WIZARD=1 zelari-code     # env equivalent of --no-wizard
zelari-code --version              # print version + exit (no TUI)
zelari-code --help                 # print help + exit (no TUI)

The wizard re-runs automatically if provider.json is missing on the next launch.

Quick Start

# Set your OpenAI-compatible API key (OpenAI, Together, Groq, custom endpoint, etc.)
export OPENAI_API_KEY=sk-...

# Or use Grok via OAuth (Device Authorization Grant — RFC 8628)
zelari-code
# Inside the TUI: /login grok
# → A code + verification URL appears; open the URL, enter the code, authorize.

# Or use GLM/Z.AI
export GLM_API_KEY=...

# Run zelari-code from any directory
zelari-code

Slash Commands

Full reference: docs/GUIDA.md (all flags, examples, skill IDs).

| Command | Description | |---|---| | /help | List all commands + loaded skills | | /exit | Exit the CLI | | /login <provider> [key] | Set API key; /login grok\|chatgpt\|anthropic starts OAuth | | /provider, /provider <id> | Show / switch LLM provider | | /provider custom <url> | Self-hosted endpoint (Ollama, LM Studio, …) | | /model <name>, /models | Set model / list discovered models | | /skill <id> [input] | Invoke a coding skill (26 built-in + SKILL.md) | | /skill-stats [id] | Skill invocation stats | | /skill-compare <id1> <id2> | Compare two skills' stats | | /council <input> | Run the 6-member council pipeline | | /zelari <input> | Run an autonomous mission — design@council then build@kraken until the MVP slice is complete | | /council-feedback <id> <1-5> | Rate a council member | | /promote-member <id> | Promote a council member to a skill | | /memory … | Search, inspect, index, consolidate, promote, diagnose, or export project memory | | /sessions, /resume <id>, /new | Session management | | /branch <name>, /branches, /checkout <name> | Session branches | | /compact, /clear | Compact / clear transcript | | /diff [--staged], /undo --yes | Git diff / revert (destructive) | | /steer <text>, /steer --interrupt <text> | Queue follow-up during a run | | /workspace … | .zelari/ artifacts + AGENTS.MD | | /update, /update --yes | Check / install CLI updates | | /mode [kraken\|council\|zelari] | Switch dispatch mode (agent/single = kraken aliases) | | /kraken [sessionId] | Tentacle radio; /kraken graph <goal> runs a parallel DAG | | /plan [goal], /build [goal] | Work phase: explore/design only vs implement (orthogonal to mode) | | /trust [path], /trust remove [path] | Folder trust for project MCP + lifecycle hooks | | /integrations | MCP presets (composio, qwen-mm-plugins, cua) | | /checkpoint [label] | Snapshot the working tree (rollback target) | | /rollback [id\|latest] | Restore a checkpoint (revert / restore files atomically) | | /index | Build / refresh the semantic search index |

TUI: shift+tab cycles kraken → council → zelari for free-form prompts (agent is a kraken alias). Use /mode when the terminal captures shift+tab. Work phase is orthogonal: /plan (no project writes) vs /build (full tools) — same axes as Desktop Mode / Phase bars.

Headless Mode

Run a single task without the TUI (CI/scripts/Desktop):

zelari-code --headless --task "Explain src/cli/main.ts" --output plain
zelari-code --headless --task "Design a REST API" --council --output json
zelari-code --headless --mode kraken --phase plan --task "Outline the change"

Useful flags: --mode kraken|council|zelari (agent=alias), --phase plan|build, --provider, --model, --history-file (multi-turn Desktop). See docs/GUIDA.md for exit codes and config helpers (--print-config, MCP, SSH).

Self-Update

Zelari Code includes a built-in update mechanism:

# Inside the TUI:
/update          # check for updates (prints current vs latest)
/update --yes    # apply update (runs npm install -g zelari-code@latest)

On startup, the CLI silently checks the npm registry. If a newer version is available, it prints a one-line hint to stderr.

Disable auto-check: ANATHEMA_DEV=1 zelari-code

Features

• 🤖 Multi-agent council — 6 roles (Caronte, Nettuno, Gerione, Plutone, Minosse, Lucifero) with feedback loops and member promotion
• 🐙 Kraken super-agent — default mode (aliases agent/single): lead that spawns task tentacles (explore / general / verify), optional git worktrees, and Kraken Graph (/kraken graph) for a parallel DAG
• ⚡ Zelari-mode — autonomous multi-run missions: a free-form prompt becomes a mission brief, then design@council → build@kraken until the MVP slice's completion.ok is green or the iteration budget runs out
• 🧮 Budget-aware mission continuation — after each mission slice a continuation gate decides repair / pivot / hold from the remaining budget and gap history (repeated gap → pivot with reduced roster; exhaustion → hold, never a false done; deterministic PASS stays the only authority)
• 🧾 Deep harness manifest — each session fingerprints its real tool surface (name + description + input schema per tool) alongside profile and resource policy, so tool or schema drift changes the manifest hash and is detectable on resume and in eval provenance
• 🚦 Eval retention gate — tiered anchor suite (eval/anchors/), versioned result store per manifest hash, and a CI regression gate comparing candidate vs last stable tag (blocking once the baseline store is seeded; honest shadow + warning until then)
• 🧠 Native shared project memory — compatible JSONL by default; opt-in SQLite V2 adds typed graph nodes, immutable history, bounded recall and shared Council/Kraken/session knowledge without MCP (guide)
• ⇧⇥ Kraken/council/zelari mode switch — shift+tab cycles free-form prompts between the kraken lead, the full council pipeline, and an autonomous mission (mode shown in the status line)
• 🎨 Rich TUI — Ink + React: native-scrollback chat stream, input bar with status line below it (mode · provider · model · session · cwd · execution timer)
• 🗂️ Live git sidebar — right-hand panel with working-tree changes (+added/-removed per file, refreshed every 4s; auto-hidden on narrow terminals)
• ⏱️ Execution timer — elapsed time of the in-flight turn in the status line (⏱ 12s), frozen as last 34s when the run completes
• 🧠 Provider-agnostic — OpenAI-compatible APIs (OpenAI, Together, Groq, custom), xAI Grok / ChatGPT / Anthropic OAuth, GLM/Z.AI, MiniMax, DeepSeek; optional ZELARI_LOCAL_CLI=claude
• 🛠️ Built-in tools — filesystem (read/write/edit), shell (bash), search (grep), web fetch/search
• 🧠 LSP code intelligence (lsp_* tools) — go-to-definition, find references, hover type, document symbols, rename symbol via real language servers (tsserver, pyright, …)
• 🌲 AST structural tools (ast_* tools) — symbol outline + find-by-name via the TypeScript compiler API, no language server needed
• 🔎 Semantic search (semantic_search + /index) — concept-level code search via embeddings, local-first
• 🌐 Browser verification (browser_check) — headless browser with click/fill/goto/wait actions, console + network + screenshot capture for visual verification of web work
• 🔁 Post-edit diagnostics loop — after every edit_file/write_file the harness runs project lint/compile (eslint, ruff, LSP-pluggable) and surfaces the errors to the model in the same turn (opt out: ZELARI_DIAGNOSTICS=0)
• 💾 Prompt-cache accounting — tracks prompt-cache hit rate per provider/model and surfaces it in the status bar (cache 73%) so you can see when a session is amortizing its prefix
• 🧷 Workspace checkpoints — /checkpoint [label] + /rollback [id|latest] use git plumbing to snapshot the working tree (tracked + untracked) and restore it atomically; every zelari-mode mission takes one before starting
• 🤝 Sub-agent delegation (task tool) — isolated tentacles: explore (read-only), general (bounded writes), verify (tests/checks); optional scope[] + acceptance[]; no nested task
• 📚 26 coding skills (+ user SKILL.md from .zelari/skills/, .claude/skills/, …) including schema-loop, computer-use-cua, qwen-mm-plugins-install-setup
• 🔄 Cross-provider failover — automatic retry with provider swap on transient errors
• 📊 Metrics + skill history — fire-and-forget logging to ~/.tmp/zelari-code/
• 🗜️ Session management — JSONL transcripts, resume across restarts, compaction
• 🌿 Branch isolation — session snapshots per branch
• 🔌 MCP — external MCP servers via .zelari/mcp.json or ~/.zelari-code/mcp.json; Desktop Extensions store for one-click install
• 🔐 SSH targets — configure hosts for deploy/monitor (password, agent, or key); tools ssh_status / ssh_run with allowlist; ZELARI_SSH=0 kill switch
• 🖥️ Zelari Desktop — Tauri 2 shell with chat UI, project tree, Settings (OAuth Sign in/Refresh/Sign out), Workbench Plan/Tasks, dual updates (app vs npm CLI), multi-turn history, optional overlay HUD
• 📱 Companion host + Android — zelari-code serve (SSE over Tailscale/LAN) + Settings → Start companion serve; MVP app in apps/companion-android/
• 🧩 Skills store (Desktop) — create/remove user & project SKILL.md; import skill from URL with the selected model; /skills picker in TUI
• 📎 @-tag paths — tag workspace files/folders in Desktop composer and CLI prompts
• ◇◆ Plan / build phase — /plan explores without project writes; /build implements with full tools (independent of kraken/council/zelari mode)
• 🛡️ Folder trust + lifecycle hooks — project MCP/hooks load only for trusted folders (/trust, zelari-code --inspect); hooks are fail-open
• 👁️ Native vision — @image.jpg (and Desktop drop-to-attach) inlines pixels to vision-capable models; no third-party vision API
• 🆕 Self-update — /update slash command + silent registry check on startup

Architecture

zelari-code (CLI, Apache-2.0)
├── src/cli/                  # Ink TUI, providers, workspace, wizard, MCP, SSH, serve
│   ├── components/           # ChatStream, InputBar, Sidebar, StatusBar, …
│   ├── slashHandlers/        # /provider, /workspace, /kraken, /trust, …
│   └── workspace/            # .zelari/ persistence + AGENTS.MD curation
├── packages/core/            # @zelari/core (Apache-2.0, npm)
│   ├── core/                 # AgentHarness — provider-neutral agent loop
│   ├── agents/               # Council API, roles, 26 skills, tool schemas
│   └── council/              # Run mode, tier banners
├── apps/desktop/             # Optional Tauri 2 shell (spawns CLI --headless)
└── apps/companion-android/   # Thin client for `zelari-code serve`

AgentHarness takes (model, provider, messages, tools) + a streaming function and yields AsyncIterable<BrainEvent>. Mixed tool batches run segmented: contiguous read-only calls in parallel, write/execute tools as serial barriers (opt out: ZELARI_PARALLEL_TOOLS=0). See MIGRATION.md for the package boundary.

Environment Variables

| Variable | Description | |---|---| | OPENAI_API_KEY | OpenAI API key | | OPENAI_MODEL | Default model (default: grok-4.5) | | OPENAI_BASE_URL | Custom OpenAI-compatible endpoint | | GLM_API_KEY | GLM/Z.AI API key | | GROK_API_KEY | xAI Grok API key (alternative to OAuth) | | CHATGPT_API_KEY | ChatGPT API key (optional if using /login chatgpt OAuth) | | ANTHROPIC_API_KEY | Anthropic API key (optional if using /login anthropic OAuth) | | ZELARI_LOCAL_CLI | Drive the harness via an external CLI (claude stream-json) | | DEEPSEEK_API_KEY | DeepSeek API key (models auto-discovered; default deepseek-v4-pro) | | MINIMAX_API_KEY | MiniMax API key | | ANATHEMA_DEV=1 | Disable silent update check on startup | | ZELARI_NO_WIZARD=1 | Skip first-run wizard | | ZELARI_NO_SHIM_REPAIR=1 | Disable auto-repair of a missing Windows bin shim on install | | ZELARI_COUNCIL_TIER=lite | Council with 3 members instead of 6 | | ZELARI_MCP=0 | Disable MCP servers | | ZELARI_CUA=0 | Disable Cua Driver MCP (desktop computer-use) | | ZELARI_CUA_COUNCIL=1 | Expose Cua MCP tools in council turns (default: agent only) | | ZELARI_SSH=0 | Disable SSH tools / targets | | ZELARI_CLI_PATH | Desktop: path to local bin/zelari-code.js monorepo entry | | ZELARI_NO_PATH_REPAIR=1 | Windows: skip npm-prefix PATH auto-repair | | ANATHEMA_FAILOVER=0 | Disable cross-provider failover | | ZELARI_MEMORY=0 | Disable project memory (.zelari/memory/) | | ZELARI_MEMORY_V2=1 | Enable native SQLite shared memory (JSONL remains the compatibility default) | | ZELARI_MEMORY_BACKEND=sqlite\|file | Explicitly select SQLite V2 or legacy JSONL | | ZELARI_MEMORY_AUTO_WRITE=0 | Keep V2 recall but disable automatic agent writes | | ZELARI_MEMORY_SEMANTIC=1 | Enable optional hybrid semantic memory recall | | ZELARI_MEMORY_MCP=1 | Enable the optional trusted external memory MCP server | | ZELARI_MEMORY_MCP_CLIENT_ID=<id> | Stable local owner id for MCP-private memories | | ZELARI_MEMORY_STRICT=1 | Fail instead of degrading when SQLite V2 cannot initialize | | ZELARI_MISSION_AUTO=1 | Auto-start Zelari missions (skip the brief confirmation) | | ZELARI_MISSION_MAX_ITER | Max implementation slices per Zelari mission (default 6; design-phase is free; impl 2+ = Minosse+Lucifero only) | | ZELARI_TASK_CONTRACT=0 | Disable the mission TaskContract (goal / constraints / acceptance criteria extracted from the brief; on by default) | | ZELARI_EVAL_RESULTS_DIR | Dev: override the eval result-store dir used by tools/eval (test/CI) | | ZELARI_MODE_MAX_TOOLS_LUCIFER | Chairman (Lucifero) tool budget in zelari-mode (default 30) | | ZELARI_DIAGNOSTICS=0 | Disable the post-edit compiler/lint diagnostics loop | | ZELARI_DIAGNOSTICS_TIMEOUT_MS | Timeout of the diagnostics loop (default 5000) | | ZELARI_AST=0 | Disable AST structural tools (ast_*) | | ZELARI_SEMANTIC=0 | Disable semantic search + /index | | ZELARI_SEMANTIC_FILE | Override the embeddings store path | | ZELARI_EMBED_MODEL | Embedding model id (default Xenova/all-MiniLM-L6-v2) | | ZELARI_BROWSER=0 | Disable browser_check | | ZELARI_LSP=0 | Disable LSP tools (lsp_*) | | ZELARI_CHECKPOINT=0 | Disable automatic workspace checkpoints in zelari-mode | | ZELARI_TOOL_OUTPUT_LINES | Lines of tool output shown in the TUI (default 8) | | ZELARI_PARALLEL_TOOLS=0 | Force serial tool execution (disable parallel read batches) | | ZELARI_MAX_PARALLEL_TOOLS | Max concurrent read-only tools per segment (default 6) | | ZELARI_MAX_TOOL_LOOP_ITERATIONS | Soft tool-loop budget per harness run | | ZELARI_MAX_TOOL_LOOP_HARD | Hard ceiling on tool-loop iterations | | ZELARI_PROVIDER_TIMEOUT_MS | Hard timeout on provider HTTP (default 5 min) | | ZELARI_MISSION_MAX_STALL | Zelari-mode: consecutive zero-write impl slices before stall | | ZELARI_KRAKEN_WORKTREE=1 | Isolate task general tentacles in git worktrees | | ZELARI_KRAKEN_GRAPH=0 | Disable Kraken Graph engine | | ZELARI_FOLDER_TRUST | 1 trust all / 0 lockdown / <path> trust one folder | | ZELARI_VISION=0 | Disable native image inlining | | ZELARI_SCHEMA_LOOP=0 | Disable world-model tools (run_backtest, …) |

See docs/GUIDA.md for the full list.

Council Workspace

The CLI persists council output (decisions, risks, docs, plan, reviews) into a project-local .zelari/ directory and auto-curates an AGENTS.MD at the project root.

Layout

.zelari/                      # auto-gitignored, per-project
├── plan.md / plan.json       # phases / tasks / milestones
├── risks.md                  # risk register (live, ordered by severity)
├── decisions/                # ADRs — 001-<slug>.md
├── reviews/                  # Minosse verdict per council run
├── docs/                     # doc drafts produced by the council
├── memory/                   # file-based project memory (zelari missions)
├── radio/                    # Kraken tentacle progress bus
├── kraken/                   # last-graph.json (DAG resume)
├── world/                    # schema-loop hypothesis / checks / timeline
└── hooks/                    # project lifecycle hooks (trusted folders only)
AGENTS.MD                     # committed at project root, auto-curated from .zelari/

Slash commands

| Command | Effect | | --- | --- | | /workspace | List all artifacts + usage hint | | /workspace show plan | Render .zelari/plan.md | | /workspace show decisions | List all ADRs (id, status, title) | | /workspace show risks | Render .zelari/risks.md | | /workspace show agents | Render AGENTS.MD (project root) | | /workspace show docs | List .zelari/docs/ drafts | | /workspace sync | Re-run AGENTS.MD auto-curation (idempotent — no-op if unchanged) | | /workspace reset --yes | Delete .zelari/ (destructive — requires confirmation) |

AGENTS.MD format

AGENTS.MD is partitioned into:

1. Manual blocks (free-form, preserved verbatim across updates) — write anything you want here.
2. Auto-managed sections delimited by <!-- zelari:auto:start section="..." --> / <!-- zelari:auto:end --> markers — overwritten each sync.

Auto-managed sections:

• tech-stack — languages, frameworks, build tools (derived from package.json)
• decisions — accepted ADRs (newest first, capped)
• conventions — code conventions observed in source tree
• build — build/test/lint commands
• open-questions — info-level risks + unsolved questions

Set ZELARI_AGENTS_MD=0 to disable AGENTS.MD auto-curation.

Storage layout internals

• Frontmatter: subset YAML (scalars, flow/sequence/block-sequence arrays, flow/block maps) — no external deps.
• Concurrency: per-key mutex (filesystem writes are serialized per artifact).
• Idempotency: hash comparison — AGENTS.MD write is skipped when no section changed (clean git diff).

See docs/plans/2026-07-01-council-workspace-cli-stubs.md for the full schema.

Documentation

| Doc | Description | |---|---| | PRINCIPLES.md | First principles (P1–P6) + enforcement map | | docs/GUIDA.md | Full user guide (Italian) | | docs/TOOLS.md | Tool map (builtin, workspace, MCP, SSH, plan phase) | | docs/media/ | English marketing stills + trailer | | CONTRIBUTING.md | Dev setup, PR expectations | | SECURITY.md | Vulnerability reporting | | CODE_OF_CONDUCT.md | Community standards | | docs/decisions/ | Architecture Decision Records | | MIGRATION.md | For library consumers of old @zelari/core import paths only (not needed for the CLI) |

Development

git clone https://github.com/N-THEM-Studio/zelari-code.git
cd zelari-code
npm install
npm run build:cli
npm link
zelari-code

Run tests

npm test

Typecheck

npm run typecheck

Eval retention gate

npm run test:eval    # eval engine + regression-gate unit tests
npm run eval:gate    # regression gate vs stored baseline (CI parity)

Anchors: eval/anchors/ (tiered) · result store: eval/results/, versioned per harness-manifest hash and seeded with node --experimental-strip-types tools/eval/runAnchors.ts · CI: .github/workflows/eval-retention-gate.yml — Tier-0 always blocking; the retention gate runs candidate anchors vs the store extracted from the last stable tag and blocks on regression once the baseline store is seeded (declared bootstrap + warning until then; never fake greens).

Related

• Product page (IT: zelari-codice) — Anathema Studio
• GitHub repository
• npm: zelari-code — CLI
• npm: @zelari/core — reusable runtime (Apache-2.0)
• Site docs (IT: documentazione)

License

Apache-2.0 © 2026 Anathema Studio.