Anathema Studio - Software Development Alghero Sardegna

$ man zelari-code

Documentazione Zelari-Code

Guida product-facing a Zelari-Code di Anathema Studio: Kraken di default, council on-demand — architettura, workflow, interfacce e limiti. Open source Apache-2.0 — codice su GitHub, installazione via npm. Desktop v2.65.0.

Torna a Zelari-CodeGitHub
  • v2.65.0
  • Apache-2.0
  • CLI · TUI · Desktop

1. Panoramica

Zelari-Code è un prodotto open source Apache-2.0 di Anathema Studio: un agente di coding orchestrato — Kraken di default, council quando il lavoro lo merita — che trasforma un'intenzione di sviluppo in lavoro concreto, con piano leggibile, implementazione assistita e verifica esplicita. Codice su GitHub; installazione con npm install -g zelari-code. Desktop attuale: v2.65.0.

Non è un semplice chat coding: separa i ruoli (intent, piano, codice, review, integrazione), rende il flusso ispezionabile e mantiene il controllo umano ai gate critici.

L'esperienza è terminal-first (CLI e TUI), con una shell Desktop opzionale per sessioni lunghe e ispezione del piano.

  • Kraken come super-agente di default e council a 6 ruoli on-demand (Caronte → … → Lucifero)
  • Mode agent · council · zelari e phase plan · build (assi ortogonali)
  • Skill on-demand e MCP (.zelari/mcp.json) per tool esterni
  • Provider LLM agnostici (OpenAI-compatible, Grok, GLM, MiniMax, DeepSeek, …)
  • In implementation mode solo Lucifero scrive codice progetto

2. Concetti chiave

Questi termini ricorrono nella CLI, in Desktop e in questa guida. Non confonderli.

  • Mode (dispatch) — agent (singolo LLM), council (pipeline a 6), zelari (missione multi-run). Toggle: Shift+Tab o /mode
  • Kraken — super-agente che decompone in slice, verifica e integra (tentacoli explore/general/verify)
  • Skill — playbook on-demand (debug, test, ADR, security, …) caricati solo quando servono
  • MCP — server esterni in .zelari/mcp.json (GitHub, filesystem, Context7, …)
  • Phase (lavoro) — plan (niente write/edit/bash sul progetto) o build (tool completi). Comandi: /plan, /build, --phase
  • Council run mode — design-phase (artifact .zelari obbligatori) o implementation (solo Lucifero muta i file progetto)
  • Framing — Caronte decompone la richiesta e delega agli specialisti
  • Plan — Nettuno produce il piano buildable; in design-phase con createPlan (fasi × task + milestone)
  • Ideation / knowledge — Gerione (idee e design docs), Plutone (knowledge-map)
  • Critique — Minosse valuta gap e rischi; non scrive product code
  • Synthesis / implement — Lucifero sintetizza; in implementation è l'unico implementer (write_file / edit_file / bash)
  • Session — transcript JSONL della CLI; ripresa con /resume

3. Il Council (deep dive)

Il council full esegue sei membri in quest'ordine (getCouncilAgents). Ogni membro vede gli output precedenti. Collaborano su un flusso esplicito invece di mescolare piano, idea, critique e codice in un'unica risposta monolitica.

Caronte

Orchestrator · Council Director

in
Richiesta utente, contesto di progetto, vincoli noti
out
Analisi + piano di delega agli specialisti (mandate)
when
Primo della pipeline; frame del problema

Nettuno

Planner · Project Planner

in
Contesto di Caronte + codebase (read tools)
out
Piano a fasi e task; in design-phase: createPlan batch (~4 fasi × ~3 task + milestone)
when
Subito dopo Caronte

Gerione

Ideator · Creative Ideator

in
Piano e framing precedenti
out
Idee/top pick; in design-phase: createDocument (journey, IA, design-tokens)
when
Dopo il piano di Nettuno

Plutone

Knowledge Architect · MindMapper

in
Richiesta e output prior
out
Mappa concetti; in design-phase: createDocument knowledge-map
when
Dopo Gerione

Minosse

Quality Critic

in
Proposte e artefatti degli specialisti
out
Score, gap, contraddizioni, miglioramenti; in design-phase: createDocument risks — non product code
when
Prima della sintesi / implementazione

Lucifero

Synthesizer · Implementer

in
Output di tutti i membri + critique di Minosse
out
Design-phase: createDocument synthesis. Implementation: unico membro che write_file/edit_file/bash sul progetto
when
Ultimo della pipeline

4. Workflow end-to-end

Pipeline council full (design-phase o implementation a seconda della richiesta e di ZELARI_COUNCIL_MODE). In implementation gli advisor restano in read-only; scrive solo Lucifero.

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

    1 · Framing

    Caronte interpreta l'obiettivo e definisce la delega agli specialisti.

  2. 02

    2 · Plan

    Nettuno produce il piano buildable. In design-phase emette createPlan (fasi, task con fileRefs/acceptance, milestone).

  3. 03

    3 · Ideate + structure

    Gerione diverge/converge su concetti e design docs; Plutone struttura la knowledge-map.

  4. 04

    4 · Critique

    Minosse espone gap, rischi e priorità di miglioramento. Non implementa codice prodotto.

  5. 05

    5 · Synthesize / implement

    Lucifero riconcilia e consegna: documento synthesis (design) oppure write/edit/bash e verifica (implementation).

  6. 06

    6 · Controllo umano

    Rivedi transcript, piano in .zelari/, diff e test. Phase plan blocca le mutate sul progetto se vuoi solo esplorare.

5. Interfacce: CLI, TUI, Desktop

Il prodotto si invoca come zelari-code. La stessa agent loop e lo stesso council servono TUI, headless e Desktop.

  • CLI / TUI — zelari-code: wizard, Shift+Tab (agent|council|zelari), /plan e /build, slash commands
  • Headless — zelari-code --headless --mode … --phase … --task … (CI, script, Desktop)
  • Desktop — shell Tauri opzionale; spawna la CLI; installer ≠ pacchetto npm globale
  • Kraken — slice, verifica e tentacoli; skill on-demand via comando skill
  • Estensioni opzionali — MCP (.zelari/mcp.json), SSH targets, LSP/AST/semantic/browser (kill switch env)

6. Provider LLM

Zelari-Code è provider-agnostic: configura i provider supportati senza lock-in a un unico vendor di piattaforma.

Famiglie tipiche: OpenAI-compatible (endpoint custom), xAI Grok (API key o OAuth), GLM/Z.AI, MiniMax, DeepSeek. La scelta influenza latenza, costo e qualità; il council e i tool restano gli stessi.

  • Separa policy di modello dal flusso del council
  • In design-phase modelli solidi sul planning aiutano Nettuno (createPlan)
  • In implementation modelli forti sul coding aiutano Lucifero (write/edit)
  • Documenta in team quali provider sono approvati (compliance / budget)

7. Controllo umano, approvazioni, limiti

Il valore di Zelari-Code non è “fare tutto da solo”, ma strutturare il lavoro in modo controllabile.

  • Puoi fermare una sessione a qualsiasi gate
  • Puoi accettare solo alcuni step del piano
  • Puoi richiedere re-plan dopo review negativa
  • Non usare il council come bypass di code review umana su sistemi critici

8. Sicurezza, privacy, dati di progetto

Tratta il codice e i secret del progetto come faresti con qualsiasi assistente AI connesso a un provider LLM.

  • Non incollare secret, chiavi API o dati personali non necessari nel prompt
  • Verifica le policy del provider LLM scelto su retention e training
  • Preferisci ambienti isolati per esperimenti su codebase private
  • Mantieni audit delle sessioni quando lavori in team

9. Best practice d'uso

Linee guida per ottenere sessioni utili e ripetibili.

  • Scrivi intent specifici: obiettivo, vincoli, Definition of Done
  • Chiedi un piano prima del codice su task non banali
  • Tieni i pezzi piccoli: meglio più step verificabili che un monoblocco
  • Usa la review come segnale, non come stamp formale
  • Documenta le decisioni architetturali emerse dal piano

10. Non-goals (cosa non è)

Chiarezza sui confini evita aspettative sbagliate.

  • Non è un IDE completo né un sostituto del tuo toolchain (git, CI, linter)
  • Non sostituisce giudizio umano: richiede review sui gate critici
  • Non garantisce correttezza automatica: richiede giudizio umano
  • Non è un servizio “magico” di deploy in produzione senza review

11. FAQ estesa

npm install -g zelari-code (Node ≥ 20.17; per provarlo senza installare: npx zelari-code@latest). Codice sorgente: github.com/N-THEM-Studio/zelari-code. Runtime riusabile: @zelari/core su npm.

Dipende dai provider LLM configurati e dall'ambiente. Il flusso del council è locale al runtime; le inferenze seguono i provider scelti.

Il modello multi-agente è orientato a workflow di sviluppo generali; i linguaggi dipendono dal contesto di progetto e dai tool collegati.

Kraken è il motore di default; il council standard (Caronte → … → Lucifero) scatta on-demand. Personalizzazioni avanzate si discutono in fase di adozione.

La CLI è pensata per essere invocabile da script. I gate umani restano obbligatori dove la policy del team lo richiede.

12. Installazione e link

Zelari-Code è open source Apache-2.0 (v2.65.0). Per supporto commerciale, integrazioni custom o partnership, contatta Anathema Studio (Alghero, Sardegna).

  • 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; per provarlo senza installare: npx zelari-code@latest)
  • Guida repo: docs/GUIDA.md · tool map: docs/TOOLS.md
  • Landing: /zelari-code (EN) · /zelari-codice (IT)
  • Contatti: /contact · /contatti
Assistant

Assistente AnathemaAssistente AI

Sempre online