Zelari-Code Documentation

1. Overview

Zelari-Code is an open-source Apache-2.0 product by Anathema Studio: a coding agent led by Kraken — with an on-demand council — that turns development intent into concrete work, with a readable plan, assisted implementation and explicit review. Source on GitHub; install with npm install -g zelari-code. Current Desktop: v2.65.0.

It is not simple chat coding: it separates roles (intent, plan, code, review, integration), keeps the flow inspectable and preserves human control at critical gates.

The experience is terminal-first (CLI and TUI), with an optional Desktop shell for long sessions and plan inspection.

• Kraken as the default super-agent plus an on-demand six-member council (Caronte → … → Lucifero)
• Modes agent · council · zelari and phases plan · build (orthogonal axes)
• On-demand skills and MCP (.zelari/mcp.json) for external tools
• Provider-agnostic LLMs (OpenAI-compatible, Grok, GLM, MiniMax, DeepSeek, …)
• In implementation mode only Lucifero writes project code

2. Core concepts

These terms appear in the CLI, Desktop, and this guide. Do not mix them up.

• Mode (dispatch) — agent (single LLM), council (6-member pipeline), zelari (multi-run mission). Toggle: Shift+Tab or /mode
• Kraken — super-agent that decomposes work into slices, verifies and integrates (explore/general/verify tentacles)
• Skills — on-demand playbooks (debug, tests, ADRs, security, …) loaded only when needed
• MCP — external servers in .zelari/mcp.json (GitHub, filesystem, Context7, …)
• Phase (work) — plan (no project write/edit/bash) or build (full tools). Commands: /plan, /build, --phase
• Council run mode — design-phase (mandatory .zelari artifacts) or implementation (only Lucifero mutates project files)
• Framing — Caronte decomposes the request and delegates to specialists
• Plan — Nettuno produces the buildable plan; in design-phase via createPlan (phases × tasks + milestone)
• Ideation / knowledge — Gerione (ideas and design docs), Plutone (knowledge-map)
• Critique — Minosse scores gaps and risks; does not write product code
• Synthesis / implement — Lucifero synthesizes; in implementation is the sole implementer (write_file / edit_file / bash)
• Session — CLI JSONL transcript; resume with /resume

3. The Council (deep dive)

A full council runs six members in this order (getCouncilAgents). Each member sees prior outputs. They collaborate on an explicit flow instead of mixing plan, ideation, critique and code into one monolithic answer.

4. End-to-end workflow

Full council pipeline (design-phase or implementation depending on the request and ZELARI_COUNCIL_MODE). In implementation, advisors stay read-only; only Lucifero writes project files.

CARONTE → NETTUNO → GERIONE → PLUTONE → MINOSSE → LUCIFERO
 frame     plan      ideate    knowledge  critic    synthesize / implement

5. Interfaces: CLI, TUI, Desktop

The product is invoked as zelari-code. The same agent loop and council power TUI, headless and Desktop.

• CLI / TUI — zelari-code: wizard, Shift+Tab (agent|council|zelari), /plan and /build, slash commands
• Headless — zelari-code --headless --mode … --phase … --task … (CI, scripts, Desktop)
• Desktop — optional Tauri shell; spawns the CLI; installer ≠ global npm package
• Kraken — slices, verification and tentacles; on-demand skills via the skill command
• Optional extensions — MCP (.zelari/mcp.json), SSH targets, LSP/AST/semantic/browser (env kill switches)

6. LLM providers

Zelari-Code is provider-agnostic: configure supported providers without a mandatory single platform vendor.

Typical families: OpenAI-compatible (custom endpoint), xAI Grok (API key or OAuth), GLM/Z.AI, MiniMax, DeepSeek. Choice affects latency, cost and quality; the council and tools stay the same.

• Separate model policy from the council flow
• In design-phase, strong planning models help Nettuno (createPlan)
• In implementation, strong coding models help Lucifero (write/edit)
• Document which providers are approved in your team (compliance / budget)

7. Human control, approvals, limits

Zelari-Code’s value is not “do everything alone”, but structuring work so it stays controllable.

• You can stop a session at any gate
• You can accept only selected plan steps
• You can request re-plan after a failed review
• Do not use the council to bypass human code review on critical systems

8. Security, privacy, project data

Treat project code and secrets the same way you would with any AI assistant connected to an LLM provider.

• Do not paste secrets, API keys or unnecessary personal data into prompts
• Check your LLM provider policies on retention and training
• Prefer isolated environments when experimenting on private codebases
• Keep session audit trails when working in teams

9. Best practices

Guidelines for useful, repeatable sessions.

• Write specific intents: goal, constraints, Definition of Done
• Ask for a plan before code on non-trivial tasks
• Keep pieces small: many verifiable steps beat one monolith
• Treat review as a signal, not a rubber stamp
• Document architectural decisions that emerge from the plan

10. Non-goals (what it is not)

Clear boundaries prevent wrong expectations.

• Not a full IDE or a replacement for your toolchain (git, CI, linters)
• Does not replace human judgment at critical gates
• Does not guarantee automatic correctness: human judgment required
• Not a magic production deploy service without review

11. Extended FAQ

12. Install & links

Zelari-Code is open source Apache-2.0 (v2.65.0). For commercial support, custom integrations or partnerships, contact Anathema Studio (Alghero, Sardinia).

• GitHub: https://github.com/N-THEM-Studio/zelari-code
• npm CLI: https://www.npmjs.com/package/zelari-code
• npm core: https://www.npmjs.com/package/@zelari/core
• Install: npm install -g zelari-code (Node ≥ 20.17; to try it without installing: npx zelari-code@latest)
• Repo guide: docs/GUIDA.md · tool map: docs/TOOLS.md
• Product landing: /zelari-code (EN) · /zelari-codice (IT)
• Contact: /contact · /contatti