🔌 Plugin e hook di Claude Code

Il plugin collega Claude Code al daemon Codelux AI sulla tua macchina: il server MCP con gli 8 strumenti, tre comandi slash e cinque hook che fanno funzionare la memoria e il blocco dei file senza che il modello debba ricordarsi di chiamare nulla.

Installazione

Oppure dentro Claude Code: <code>/plugin marketplace add codeluxai/codelux</code>, poi <code>/plugin install codelux@codelux</code>. Gli hook richiedono <code>bash</code> e <code>curl</code> (su Windows, Git Bash). Se il daemon non è in esecuzione ogni hook resta silenzioso: Claude Code funziona come se il plugin non ci fosse.

I cinque hook

Il blocco AGENTS.md / CLAUDE.md

A ogni avvio di sessione e a ogni <code>memory_set</code>, Codelux AI riscrive il blocco tra <code>&lt;!-- codelux:start --&gt;</code> e <code>&lt;!-- codelux:end --&gt;</code> in <code>&lt;project&gt;/AGENTS.md</code> (creato se manca) e, se il file esiste, in <code>&lt;project&gt;/CLAUDE.md</code>: stato, prossimo passo, trappole e decisioni recenti, al massimo 60 righe. Il testo fuori dai marcatori non viene mai toccato. Gli agenti che non leggono gli hook leggono comunque questo file.

Comandi slash

Codex e Gemini CLI (sperimentale)

Gli stessi script funzionano con qualsiasi agente che supporti gli hook a comando. La cartella del plugin include due file già pronti: <code>hooks/codex.hooks.json</code> per Codex (copialo in <code>&lt;repo&gt;/.codex/hooks.json</code>) e <code>hooks/gemini.settings.json</code> per Gemini CLI (unisci il suo oggetto <code>hooks</code> a <code>&lt;repo&gt;/.gemini/settings.json</code>). Il server MCP ha lo stesso URL per ogni agente. Ciò che gli hook non coprono lo copre il blocco <code>AGENTS.md</code>.

🤖 Configura il tuo agente AI

Codelux AI raggiunge ogni agente con due canali: il server MCP (gli strumenti) e gli hook (ciò che accade senza che il modello debba chiederlo). Qui sotto trovi la configurazione completa, da copiare, per ogni provider.

Cosa ti danno gli hook

Tutto il procedimento, passo per passo

<b>Le app dei provider devono avere gli hook Codelux AI attivi: sessione principale e sotto-agenti mandano tutto.</b> Con gli hook su tutti gli strumenti (PreToolUse + PostToolUse + PostToolUseFailure per Claude Code, PreToolUse/PostToolUse per Codex, BeforeTool/AfterTool per Gemini CLI) Codelux AI registra una riga per ogni chiamata, nativa o Codelux AI, della sessione e di ogni sotto-agente, sotto il nome dell'agente.

Cosa contiene una riga: provider, sessione o sotto-agente, strumento, gli argomenti essenziali (Read: file e righe; Grep/Glob: pattern, percorso, glob; Edit/Write: file e righe o byte toccati; Bash: il comando tagliato a 200 caratteri; Agent: tipo e descrizione; MCP: strumento e argomenti chiave), la dimensione della risposta in byte e righe, la durata e l'esito. Mai il contenuto di un file, un output o il testo di una modifica; chiavi, token e password in comandi e argomenti diventano <code>[redacted]</code>. Tutto resta sulla tua macchina (l'archivio locale del progetto, 30 giorni): niente va al server, niente entra negli eventi del Team.

La vista <b>Procedimento</b> dell'app (per progetto, per agente, per giorno) mostra la sequenza con i tempi, i file riletti senza che fossero cambiati, i file grandi letti interi quando bastava un simbolo, la quota di chiamate Codelux AI, i token stimati per lettura e i giri risparmiabili, con l'alternativa concreta (<code>code_context X</code> invece di 2.000 righe). Si esporta in Markdown, o si legge con <code>GET /api/project/{id}/procedure?from=&amp;to=&amp;who=&amp;format=md</code> o <code>codelux procedure &lt;projectid&gt;</code>.

Suggerimenti all'agente in corso: solo quando il risparmio è chiaro, una riga sobria nel suo contesto («hai già letto X alle 10:59 (righe 1-200) e non è cambiato», «X è un simbolo indicizzato: code_context X»), al massimo 2 per turno, mai un blocco. Si spengono per progetto nella vista Procedimento.

Leggere solo quello che serve: <code>GET /api/project/{id}/read?file=&amp;from=&amp;to=</code> (REST), <code>codelux read &lt;projectid&gt; &lt;file&gt; &lt;from&gt; &lt;to&gt;</code> (CLI) e, su MCP, <code>code_context</code> con <code>name="&lt;file&gt;:&lt;from&gt;-&lt;to&gt;"</code> rispondono le righe chieste (al massimo 400), numerate, con il totale del file, i token stimati e l'intervallo successivo; <code>code_context name="&lt;file&gt;"</code> risponde lo schema del file (simboli con le loro righe). Ogni lettura via Codelux AI finisce nello stesso Procedimento.

In sintesi

Prima di cominciare

• Codelux AI è in esecuzione e il progetto è aggiunto nell'app. L'indirizzo MCP è <code>http://localhost:8766/mcp</code>; se Codelux AI gira su un'altra porta, usa la tua.
• Gli hook richiedono <code>bash</code> e <code>curl</code>; su Windows, Git Bash.
• Codex e Gemini CLI: scarica la cartella del plugin da <a href="https://github.com/codeluxai/codelux" rel="noopener" target="_blank">github.com/codeluxai/codelux</a> e, nei file qui sotto, sostituisci <code>CODELUX_PLUGIN</code> con il percorso completo della cartella che contiene <code>scripts/</code>. Con un'altra porta, avvia l'agente con la variabile <code>CODELUX_PORT</code> impostata.

Il blocco di AGENTS.md

Ogni agente legge lo stesso blocco tra <code>&lt;!-- codelux:start --&gt;</code> e <code>&lt;!-- codelux:end --&gt;</code>: poche righe fisse che dicono quali strumenti Codelux AI usare e che la memoria arriva da sola o con <code>memory_get</code>. Non ha data né stato, quindi è identico a ogni sessione e non invalida la cache del prompt del provider. L'hook di inizio sessione lo tiene aggiornato; senza hook, lancia questo comando una volta dalla cartella del progetto:

Crea <code>AGENTS.md</code> con il blocco se manca (e <code>CLAUDE.md</code> con la sola riga <code>@AGENTS.md</code>); il testo fuori dai marcatori non viene mai toccato. Se la cartella non è un progetto registrato in Codelux AI, non scrive nulla.

Claude Code

Supporto completo. Il plugin porta tutto: il server MCP, gli hook e i comandi slash. Non c'è niente da copiare a mano.

1. Installa il plugin:
   claude plugin marketplace add codeluxai/codelux claude plugin install codelux@codelux
   oppure, dentro Claude Code, <code>/plugin marketplace add codeluxai/codelux</code> e poi <code>/plugin install codelux@codelux</code>. Con un'altra porta: <code>claude plugin install codelux@codelux --config port=&lt;porta&gt;</code>, poi riavvia Claude Code.
2. Riavvia Claude Code nella cartella del progetto e scrivi <code>/codelux:status</code> per verificare che sia connesso.
3. File di istruzioni: a inizio sessione il plugin scrive il blocco in <code>AGENTS.md</code> e, se <code>CLAUDE.md</code> non esiste, lo crea con una riga che lo importa. Un <code>CLAUDE.md</code> esistente che non importa <code>AGENTS.md</code> riceve il blocco in coda.
   @AGENTS.md
4. Hook: il file è <code>hooks/hooks.json</code> dentro il plugin, già collegato. Questa è la parte che prende e rilascia il blocco (gli altri hook sono in <a href="#" data-doc-go="hooks">Plugin e hook di Claude Code</a>):
   "PreToolUse": [ { "matcher": "Edit|Write|MultiEdit|NotebookEdit", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/edit-lock.sh\" acquire", "timeout": 10 } ] } ], "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit|NotebookEdit", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/edit-lock.sh\" release", "timeout": 10 } ] } ], "PostToolUseFailure": [ { "matcher": "Edit|Write|MultiEdit|NotebookEdit", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/edit-lock.sh\" release-failed", "timeout": 10 } ] } ]
   E la parte che manda il procedimento (tutti gli strumenti, matcher <code>.*</code>):
   "PreToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/session-track.sh\" pre", "timeout": 5 } ] } ], "PostToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/session-track.sh\" post", "timeout": 5 } ] } ], "PostToolUseFailure": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/session-track.sh\" post-fail", "timeout": 5 } ] } ]
5. MCP: il plugin registra il server <code>codelux</code>. Senza il plugin, vedi <a href="#" data-doc-go="ide">Configurazione IDE (MCP)</a>.

Codex

Sperimentale. Il formato degli hook viene dalla documentazione di Codex del 28/09/2026; alcuni campi non sono confermati (vedi sotto).

1. Aggiungi il server MCP nella configurazione di Codex, <code>~/.codex/config.toml</code>:
   [mcp_servers.codelux] url = "http://localhost:8766/mcp"
   Questa forma è presa dalla documentazione MCP di Codex e non è verificata da noi su ogni versione: se Codex non elenca gli strumenti, controlla lì la sintassi esatta.
2. File di istruzioni: <code>AGENTS.md</code>. Il blocco lo scrive l'hook di inizio sessione, o a mano con il comando qui sopra.
3. Copia questo file in <code>&lt;progetto&gt;/.codex/hooks.json</code> (o in <code>~/.codex/hooks.json</code> per tutti i progetti), sostituendo <code>CODELUX_PLUGIN</code>:
   { "description": "Codelux hooks for Codex. Copy to <repo>/.codex/hooks.json (or ~/.codex/hooks.json) and replace CODELUX_PLUGIN with the absolute path of the folder that holds scripts/. Same scripts as the Claude Code plugin; plain stdout is added as context, exit 2 on acquire blocks the edit with the stderr reason. PreToolUse/PostToolUse on every tool (.*) feed the procedure trace (377). See hooks/OTHER-AGENTS.md for the fields we could not verify.", "hooks": { "SessionStart": [ { "matcher": "startup|resume|clear|compact", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-start.sh\" --agent=codex", "timeout": 10, "additionalContextLimit": 12500 } ] }, { "matcher": "startup|resume|clear|compact", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" start --agent=codex", "timeout": 5 } ] } ], "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/prompt-memory.sh\" --agent=codex", "timeout": 5 }, { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" prompt --agent=codex", "timeout": 5 } ] } ], "PreToolUse": [ { "matcher": "Edit|Write|MultiEdit|apply_patch", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/edit-lock.sh\" acquire --agent=codex", "timeout": 10 } ] }, { "matcher": ".*", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" pre --agent=codex", "timeout": 5 } ] } ], "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit|apply_patch", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/edit-lock.sh\" release --agent=codex", "timeout": 10 } ] }, { "matcher": ".*", "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" post --agent=codex", "timeout": 5 } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" stop --agent=codex", "timeout": 5 } ] } ] } }
4. Riavvia Codex.

Non confermato

• I nomi degli strumenti di modifica: l'esempio della documentazione è <code>Edit|Write</code> (modifiche ai file tramite <code>apply_patch</code>); noi accettiamo <code>Edit|Write|MultiEdit|apply_patch</code> per sicurezza.
• Il campo che porta il percorso modificato per <code>apply_patch</code>. Lo script cerca <code>file_path</code>, <code>notebook_path</code> o <code>path</code>; se Codex manda solo il testo della patch, il blocco non fa nulla (non blocca mai).
• L'unità di <code>timeout</code> (supponiamo secondi) e una variabile con la cartella del progetto (gli script usano la cartella di lavoro, o <code>CODEX_PROJECT_DIR</code> se impostata).
• Se Codex manda un <code>session_id</code> agli hook. Senza, il tracciamento della sessione viene saltato e le chiamate MCP hanno un codice per connessione.

Gemini CLI

Sperimentale. Il formato degli hook viene dal riferimento di Gemini CLI del 28/09/2026; alcuni campi non sono confermati (vedi sotto). Tutto va in <code>&lt;progetto&gt;/.gemini/settings.json</code> (o in <code>~/.gemini/settings.json</code>).

1. Aggiungi il server MCP:
   { "mcpServers": { "codelux": { "httpUrl": "http://localhost:8766/mcp" } } }
   Questa forma è presa dalla documentazione MCP di Gemini CLI e non è verificata da noi su ogni versione: se gli strumenti non compaiono, controlla lì la sintassi esatta.
2. File di istruzioni: Gemini legge <code>GEMINI.md</code>, non <code>AGENTS.md</code>. Puoi puntarlo su <code>AGENTS.md</code> nello stesso file di impostazioni, oppure copiare il blocco in <code>GEMINI.md</code>:
   { "contextFileName": "AGENTS.md" }
   L'impostazione si chiama <code>contextFileName</code> nelle note del nostro plugin; se la tua versione di Gemini CLI la chiama o la annida in modo diverso, controlla il suo riferimento delle impostazioni.
3. Unisci questo oggetto <code>hooks</code> nello stesso file, accanto alle chiavi qui sopra, sostituendo <code>CODELUX_PLUGIN</code>. Gli script girano con <code>--json</code> perché Gemini vuole solo JSON su stdout:
   { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "name": "codelux-memory", "description": "Codelux: project memory in context at session start; refreshes the AGENTS.md/GEMINI.md block", "command": "bash \"CODELUX_PLUGIN/scripts/session-start.sh\" --json --agent=gemini", "timeout": 10000 } ] }, { "hooks": [ { "type": "command", "name": "codelux-session", "description": "Codelux: session code and usage tracking (silent)", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" start --agent=gemini", "timeout": 5000 } ] } ], "BeforeAgent": [ { "hooks": [ { "type": "command", "name": "codelux-prompt-memory", "description": "Codelux: relevant memory for this prompt as additionalContext (nothing when nothing is found)", "command": "bash \"CODELUX_PLUGIN/scripts/prompt-memory.sh\" --json --agent=gemini", "timeout": 5000 }, { "type": "command", "name": "codelux-session-prompt", "description": "Codelux: count the prompt; rarely one hint about the last turn", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" prompt --json --agent=gemini", "timeout": 5000 } ] } ], "BeforeTool": [ { "matcher": "write_file|replace|edit", "hooks": [ { "type": "command", "name": "codelux-lock-acquire", "description": "Codelux: take the file lock (local + Team) before an edit; exit 2 with the reason when refused", "command": "bash \"CODELUX_PLUGIN/scripts/edit-lock.sh\" acquire --agent=gemini", "timeout": 10000 } ] }, { "matcher": ".*", "hooks": [ { "type": "command", "name": "codelux-session-pre", "description": "Codelux: start of every tool call for the procedure trace, file read (path+hash), MCP call announcement; rarely one hint as additionalContext", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" pre --json --agent=gemini", "timeout": 5000 } ] } ], "AfterTool": [ { "matcher": "write_file|replace|edit", "hooks": [ { "type": "command", "name": "codelux-lock-release", "description": "Codelux: release the file lock after an edit", "command": "bash \"CODELUX_PLUGIN/scripts/edit-lock.sh\" release --agent=gemini", "timeout": 10000 } ] }, { "matcher": ".*", "hooks": [ { "type": "command", "name": "codelux-session-post", "description": "Codelux: one row of the procedure trace (tool, essential arguments, response size, duration; never contents)", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" post --agent=gemini", "timeout": 5000 } ] } ], "AfterAgent": [ { "hooks": [ { "type": "command", "name": "codelux-session-stop", "description": "Codelux: read the new usage numbers (silent)", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" stop --agent=gemini", "timeout": 5000 } ] } ], "SessionEnd": [ { "hooks": [ { "type": "command", "name": "codelux-session-end", "description": "Codelux: close the task and write the usage report (silent)", "command": "bash \"CODELUX_PLUGIN/scripts/session-track.sh\" end --agent=gemini", "timeout": 10000 } ] } ] } }
4. Riavvia Gemini CLI.

Non confermato

• <code>SessionStart</code> non elenca <code>additionalContext</code> tra i suoi campi nel riferimento; lo script lo invia comunque. Se viene ignorato, lo stato lo porta comunque il blocco in <code>AGENTS.md</code> / <code>GEMINI.md</code>.
• I nomi degli strumenti di modifica integrati (supponiamo <code>write_file</code>, <code>replace</code> e <code>edit</code>) e il campo del percorso nel loro input (<code>file_path</code>). Se differiscono, il blocco non fa nulla e non blocca mai.
• Se Gemini manda un <code>session_id</code> agli hook (stessa conseguenza che per Codex) e una variabile con la cartella del progetto: nessuna è documentata, gli script usano la cartella di lavoro.

Cursor

Cursor non ha hook: tutto passa dal server MCP e da una regola che dice all'agente cosa chiamare.

1. Aggiungi il server a <code>.cursor/mcp.json</code> nel progetto (o a <code>~/.cursor/mcp.json</code> per tutti i progetti):
   { "mcpServers": { "codelux": { "url": "http://localhost:8766/mcp" } } }
2. Crea la regola <code>.cursor/rules/codelux.mdc</code>:
   --- description: Codelux project memory alwaysApply: true --- This project uses Codelux (MCP server "codelux"). - At the start of a task call memory_get with no arguments and continue from it. - Before relying on a name or a path, check it with code_query or code_context. - Write files through code_edit, so the file is locked against other agents and the edit lands on the Timeline with its diff. - When you finish, call memory_set once: summary, status, next, traps, decisions.
3. Riavvia Cursor, o ricarica i suoi server MCP.

Dichiara chi sei: un nome su ogni canale

Ogni agente si dà un nome in codice breve (<code>w375</code>, <code>tree-blocks</code>) e lo passa su ogni canale: argomento MCP <code>agent</code>, REST <code>agent=</code> o <code>X-Codelux AI-Agent</code>, CLI <code>--agent=</code>. Codelux AI lo unisce alla sessione dell'host (e al sotto-agente), così le modifiche viste dagli hook, le chiamate MCP e quelle REST o CLI sono UNA riga nella timeline: il nome come titolo, l'host (Claude Code, Claude Code sotto-agente, Codex, Gemini CLI, Cursor, REST, Altro agente) accanto, l'id di sessione nel tooltip. Una sessione che non ha ancora detto il suo nome appare <i>in attesa del nome</i> e lo prende alla prima chiamata che lo dà, anche per quello che ha fatto prima. Con il plugin di Claude Code non serve altro; gli altri host possono passare anche la sessione, vedi <a href="#" data-doc-go="curl">REST / cURL</a>.

Verifica che funzioni

Dopo una breve sessione, memorie, modifiche e blocchi dell'agente sono sulla timeline con il suo nome. Rileggili via REST:

🖥 Configurazione dell'IDE (MCP)

Codelux AI parla MCP nativo. Una riga di configurazione lo collega a qualsiasi editor o agente compatibile con MCP. Senza il plugin di Claude Code non ci sono hook: l'agente legge la sua memoria quando chiama <code>memory_get</code> (o dal blocco <code>AGENTS.md</code>) e il blocco del file lo prende <code>code_edit</code> invece che l'editor stesso.

Claude Code (senza il plugin)

Il <a href="#" data-doc-go="hooks">plugin</a> è il modo consigliato. A mano, aggiungi a <code>.mcp.json</code> nella radice del progetto (o a <code>~/.claude.json</code> per tutti i progetti):

Cursor

Aggiungi a <code>.cursor/mcp.json</code> nel progetto (o a <code>~/.cursor/mcp.json</code> per tutti):

VS Code (Copilot Chat)

Aggiungi a <code>.vscode/mcp.json</code> nel tuo workspace:

Windsurf

Aggiungi a <code>~/.codeium/windsurf/mcp_config.json</code>:

JetBrains (AI Assistant)

Impostazioni → Strumenti → AI Assistant → Model Context Protocol → Aggiungi server → URL <code>http://localhost:8766/mcp</code>.

Zed

Impostazioni → <code>context_servers</code> → aggiungi Codelux AI con lo stesso URL.

Qualsiasi altro client MCP

Codelux AI espone MCP standard su <code>http://localhost:8766/mcp</code> (HTTP in streaming; il vecchio trasporto SSE resta su <code>/sse</code>). Se il tuo strumento parla MCP, funziona. Ogni trasporto elenca gli 8 strumenti principali; aggiungi <code>?profile=full</code> all'URL per elencare anche gli altri.

🧰 Strumenti MCP

8 strumenti, elencati di default da ogni trasporto. Una volta connessa, la tua AI sceglie quello giusto; con il plugin di Claude Code la prima lettura e il blocco del file avvengono dagli hook, senza una chiamata.

Memoria

Note

Controllo sul codice

Scrittura e agenti

Una sessione con il plugin

1. La sessione inizia: l'hook mette nel contesto la memoria più recente: cosa è stato fatto, cosa viene dopo, le trappole
2. Scrivi un prompt: se una codemap, un fatto o una decisione corrisponde, l'hook la aggiunge; altrimenti nulla
3. <code>code_query</code> / <code>code_context</code>: verifica un nome o una dipendenza prima di toccarlo
4. Modifica con gli strumenti di Claude Code: l'hook prende il blocco prima e lo rilascia dopo
5. <code>notes_set</code>: un todo per te, un modulo quando serve una risposta, una decisione e il suo perché
6. <code>memory_set</code>: la sessione si chiude con la sua memoria; l'hook Stop lo ricorda al modello se si è dimenticato

Ognuno di questi passi è un evento nella <a href="#" data-doc-go="timeline">Timeline</a>.

🕒 Timeline

La Timeline è il registro di tutto ciò che succede su un progetto, emesso da Codelux AI stesso: tu non ci scrivi mai, e nulla va perso: un'eliminazione è un evento che conserva il contenuto precedente.

Cosa ci finisce

Dove leggerla

• <b>Scheda Timeline</b> della dashboard: gli eventi in ordine, con filtri per tipo, argomento, autore, periodo e file; un clic apre l'originale: la nota, la memoria, il diff del file, il commit.
• <b>Per l'agente:</b> <code>memory_get</code> con <code>events: true</code>, con gli stessi filtri.
• <b>In un team:</b> ogni evento arriva alla macchina di ogni membro, cifrato con la chiave del team, con l'indicazione di chi l'ha fatto.

🌐 REST / cURL

Ogni strumento è anche un normale endpoint HTTP. Script, pipeline CI, strumenti su misura, editor datati: tutto ciò che sa fare una chiamata HTTP può usare Codelux AI.

URL di base

<code>{project}</code> è il nome di un progetto indicizzato. Elencali con <code>/api/projects</code>.

<b>Di' chi sei.</b> Ogni chiamata qui sotto che legge o scrive il progetto deve indicare l'agente che la fa, allo stesso modo su MCP, REST e CLI: <code>agent=&lt;nome&gt;</code> nella query o nel corpo JSON, oppure l'header <code>X-Codelux AI-Agent: &lt;nome&gt;</code> (CLI: <code>--agent=&lt;nome&gt;</code> o la variabile <code>CODELUX_AGENT</code>; MCP: l'argomento <code>agent</code>, compilato dal client). Senza, la chiamata viene rifiutata con <code>400 agent required</code>; con il nome, la timeline mostra l'agente. Per chiamare un tool MCP con il suo nome e i suoi argomenti: <code>POST /api/project/{project}/tool/{name}</code>.

<b>Stesso agente, stessa riga.</b> Per legare una chiamata REST alla sessione dell'agente (quella che riportano i suoi hook), aggiungi <code>session=&lt;id sessione dell'host&gt;</code> e <code>provider=claude-code|codex|gemini|cursor|other</code>, più <code>subagent=&lt;id&gt;</code> dentro un sotto-agente; oppure gli header <code>X-Codelux AI-Session</code>, <code>X-Codelux AI-Provider</code>, <code>X-Codelux AI-Subagent</code> (CLI: <code>--session</code>, <code>--provider</code>, <code>--subagent</code> o le variabili <code>CODELUX_SESSION</code>, <code>CODELUX_PROVIDER</code>, <code>CODELUX_SUBAGENT</code>). Con il plugin di Claude Code l'inizio sessione imposta <code>CODELUX_SESSION</code> e <code>CODELUX_PROVIDER</code> in ogni comando Bash, e l'hook legge il nome in un comando che chiama Codelux AI: basta il nome. Senza alcun id di sessione l'agente è una riga per nome, mostrata come <i>Altro agente</i>.

Ricerca e lettura

Analisi

Memoria, note e Timeline

Scritture e git

Gestione

⌨️ Comandi CLI

Il binario funziona anche da CLI: utile per controlli rapidi senza lasciare il terminale.

Esegui <code>codelux.exe</code> (Windows) o <code>./codelux</code> (Linux) senza argomenti per avviare il server. Per l'uso da terminale sono disponibili questi sottocomandi:

Lettura e ricerca

Memoria e note

Scritture e indice

Sessione di esempio

📊 Dashboard web

Codelux AI include una dashboard web integrata su <code>http://localhost:8766</code>: gestisci ogni progetto dal browser, anche quando Codelux AI gira su un server remoto.

Schede

Installazione su server / headless

Esegui Codelux AI su un server e apri la dashboard da qualsiasi browser: accesso web, barra laterale multi-progetto, configurazione per progetto.

Progetti e piani

Codelux AI continua a seguire e indicizzare <b>ogni</b> progetto che registri, in ogni piano: il piano decide su cosa puoi agire, non cosa viene tenuto aggiornato. Con <b>Free</b> un solo progetto è attivo alla volta: gli altri mostrano l'azione <i>Attiva questo progetto</i> al posto delle schede, e gli strumenti restano disattivati finché non cambi progetto, cosa che fai dall'app. Con <b>Multi</b> e <b>Team</b> tutti i progetti sono attivi insieme, senza limiti di attivazione.

👥 Team

Il piano Team condivide un progetto tra le persone che inviti. Memorie, note, Timeline, chat e cronologia delle modifiche viaggiano tra le macchine come eventi cifrati; il semaforo dei file e chi è online sono coordinati in tempo reale. Codice e indice non lasciano mai la macchina di nessuno, e la chiave che protegge i dati condivisi non arriva mai a noi.

Dove sta ogni cosa

1. Acquista i posti

Il piano Team è un abbonamento annuale del proprietario del team, con prezzo per posto e un numero minimo di posti: entrambi sono nella <a href="/pricing">pagina dei prezzi</a>. I posti contano <b>persone distinte</b> in tutti i team che possiedi, proprietario incluso: la stessa persona in due dei tuoi team usa un solo posto. I membri entrano con il proprio account e non hanno bisogno di un piano proprio.

2. Crea il team sul sito

Nella <a href="/console">Console</a> apri <b>Team → Nuovo team</b>: dagli un nome, scegli <b>un progetto</b> dall'elenco dei progetti del tuo account, aggiungi gli indirizzi email dei membri e scegli come il team condivide i file (<b>Cloni Git</b> o <b>Cartella condivisa</b>, vedi passo 7). Un team = un progetto; per un altro progetto crea un altro team. Ogni membro riceve un invito via email (se non ha ancora un account, il link lo porta prima alla registrazione) e lo accetta dalla propria Console. Del contenuto del team sul sito non è mai visibile nulla.

3. L'app del proprietario crea le chiavi

Il Codelux AI del proprietario genera, una volta, una <b>chiave madre</b> (256 bit casuali) in <b>Impostazioni → Chiavi</b> e la conserva sigillata su quel computer. La chiave di ogni team si <b>ricava</b> da lei, versione per versione; il nostro server conserva solo un valore di verifica pubblico per team e versione, che non rivela nulla della chiave. Il proprietario può mostrare e copiare la chiave madre dietro conferma, ed esportarla in un file (protetto da passphrase, consigliato) per preparare un altro computer. Nessun pulsante del sito o dell'app ci invia mai una chiave.

4. Dai la chiave ai membri

• <b>Copia chiave del team</b>: in Impostazioni → Chiavi il proprietario copia la chiave di un team (inizia con <code>cdx-t-</code>) e la manda ai membri di quel team per un canale di cui si fidano (di persona, un messaggio, un gestore di password). Apre solo quel team; la chiave madre non si dà mai ai membri.
• <b>Incolla la chiave del team</b>: il membro la incolla nel riquadro del progetto del team; spazi, trattini e maiuscole non contano, e l'app la confronta con il valore di verifica del server prima di tenerla (una chiave sbagliata è rifiutata subito).

Ogni membro conserva ogni versione della chiave che riceve, così gli eventi scritti prima di una rotazione restano leggibili sulla sua macchina.

5. Punta ogni macchina alla cartella del progetto

I progetti condivisi compaiono nella barra laterale sotto <b>Condivisi con te</b>, raggruppati per team. Sulla macchina del proprietario la cartella viene presa dall'elenco dei progetti; su ogni altra macchina il membro sceglie <b>Imposta cartella su questa macchina…</b> e indica il percorso del suo clone (Cloni Git) o della cartella condivisa (Cartella condivisa). Il percorso è registrato per macchina, quindi lo stesso progetto può stare in percorsi diversi su computer diversi. Un progetto condiviso è pronto quando la macchina ha sia la cartella sia la chiave.

6. La scheda Team

Quando il progetto selezionato appartiene a un team, la dashboard ha in più la scheda <b>Team</b>: la chat con i suoi canali — il canale del team, i messaggi diretti tra due membri e i gruppi creati dal proprietario o da un admin — l'elenco dei membri con chi è online, e i lock dei file che mostrano chi sta modificando cosa. Note, journal, fatti e CodeMap riportano l'autore di ogni voce e un filtro (<i>Tutti · Io · un membro</i>). Senza la chiave la scheda offre solo <i>Incolla la chiave del team</i>.

7. Cloni Git o cartella condivisa

In entrambe le modalità la regola è la stessa: le scritture sul progetto condiviso passano solo mentre il servizio realtime che tiene i blocchi è raggiungibile. Quando non lo è, le modifiche al progetto condiviso tramite l'hook di Claude Code su Edit e Write vengono rifiutate con un messaggio chiaro, mai applicate alla cieca.

8. Membri con il piano Free

Un membro coperto dai posti del proprietario ha diritto alla <b>build Team</b>: la sezione Download della sua Console la mostra come <i>Build Team (coperta da &lt;team&gt;)</i>. La scarica, accede con il proprio account e lavora sul progetto condiviso con blocchi, presenza e chat; i suoi progetti personali seguono il suo piano (con Free, un progetto attivo per macchina). La build Free pubblica non ha il client realtime: con la cartella e la chiave può leggere la conoscenza condivisa, ma ogni scrittura sul progetto condiviso risponde <i>Serve la build Team</i>.

9. Rimuovere un membro, ruotare la chiave

I membri si rimuovono dal sito; la rimozione toglie subito l'accesso ai nuovi eventi, ma quello che è già arrivato sulla loro macchina resta lì. Quando conta, il proprietario preme <b>Gira chiave</b> in Impostazioni → Chiavi: il numero di versione sale e i dati nuovi si sigillano con la chiave nuova; i membri che restano continuano a leggere i dati vecchi e ricevono la chiave nuova dal proprietario (<i>Incolla la chiave del team</i>). Girala anche ogni volta che sospetti una fuga della chiave.

10. Macchine, offline e quando il piano scade

• <b>Un solo Codelux AI per macchina.</b> Accedere con lo stesso account su un'altra macchina subentra a quella precedente, che viene disconnessa (vince l'ultimo accesso). Vale per ogni membro.
• <b>Offline.</b> L'app si annuncia al server delle licenze ogni minuto; dopo tre controlli falliti è offline e, fino al prossimo riuscito, le scritture sui progetti condivisi vengono rifiutate: la stessa regola «chiuso in caso di errore» di un'interruzione del realtime. Non c'è alcun periodo di tolleranza offline in nessun piano.
• <b>Piano scaduto o posti superati.</b> Il team va in stato dormiente: il suo progetto condiviso non è più autorizzato per i membri, che vedono <i>Piano scaduto</i>. Non viene cancellato nulla e nessuna chiave viene toccata: le chiavi restano su ogni macchina, gli eventi restano sul server e tutto riprende al rinnovo. Nel frattempo il proprietario può ancora rimuovere membri o eliminare il team.
• <b>Eliminare il team.</b> Rimuove dai nostri server ogni evento cifrato e tutti i metadati del team. Ciò che ogni membro ha già sulla propria macchina resta lì e rimane suo.

11. Ruoli: Admin, Manager, Membro

<b>Admin</b>: acquista i posti e amministra l'organizzazione dalla <a href="/console">Console</a>: crea team, invita persone, assegna ciascuno come <b>Manager</b> o <b>Membro</b> di ogni team, nomina gli <b>Admin</b> dell'organizzazione, configura SSO e SCIM. <b>Manager</b>: coordina un team nell'app: <b>Compiti</b> (chiave, titolo, assegnatario, data di inizio e di scadenza, stato, checklist, % pianificata ed effettiva) come elenco, bacheca e Gantt, condivise con cifratura end-to-end come le note; <b>Genera report</b> crea uno standup per membro per giorno solo dalla Timeline (memorie, checkpoint, todo chiusi, modifiche ai file, blocchi, compiti spostati), mai dalla chat, e il manager conferma la % effettiva; <b>Persone</b> del suo team con gli agenti visti, l'ultima attività e un download per membro (senza chat) che viene a sua volta registrato nella Timeline; utilizzo e costi per membro. <b>Membro</b>: lavora con gli agenti e vede il piano del team, il proprio piano, l'utilizzo, la Timeline e la chat. Una persona può avere più ruoli. Nell'app l'elenco dei progetti è raggruppato: progetti personali, poi i team di cui sei membro, poi i team che gestisci. Ospitato da noi, un team ha pianificazione Codelux AI, chat, standup, Timeline, memoria, semaforo, utilizzo, costi e audit, e nessun connettore.

12. Accesso, SSO, SCIM e admin dell'organizzazione

Ogni account può accedere con email e password più un codice via email, oppure con Google, GitHub o Slack. Il proprietario di un piano Team può collegare il provider di identità dell'azienda tramite <b>OIDC o SAML 2.0</b> per i domini verificati, imporre loro l'SSO (il proprietario mantiene ogni metodo di accesso come via di rientro) ed emettere un token <b>SCIM 2.0</b>: una persona disattivata nel provider viene rimossa da tutti i team del proprietario, disconnessa ovunque e viene richiesta una rotazione della chiave. In <b>Admin</b> il proprietario nomina gli <b>admin dell'organizzazione</b>, che amministrano tutti i team del proprietario ma non possono cambiare la fatturazione né eliminare l'organizzazione. I documenti per la revisione del tuo reparto IT sono nella pagina <a href="/security">Sicurezza</a>.

13. Integrazioni: l'hub aziendale

Le integrazioni non fanno parte del nostro servizio ospitato. Con l'hub aziendale, <code>codelux-hub</code> (un programma che gestisce la tua azienda, incluso in Team ed Enterprise), un team ottiene anche le notifiche di Jira, Linear, Asana, Azure Boards, GitHub, GitLab e Slack, eseguite dall'hub e sempre attive. L'Admin collega una volta sola ogni provider per l'organizzazione; il Manager di un team sceglie tra questi il progetto Jira, il repository o il canale Slack del team, senza maneggiare alcun token. Un'organizzazione è interamente sul nostro servizio ospitato o interamente sul suo hub, e un pacchetto di migrazione sposta un team dall'uno all'altro. Registra e scarica l'hub da <b>Il mio account › Download › Hub</b> nella <a href="/console">Console</a>. Non vediamo mai il tuo codice, le memorie, la Timeline né i tuoi token.

Cosa non facciamo

• Non riceviamo, conserviamo né inoltriamo mai la chiave del team. Non esiste deposito né recupero: se tutti i membri la perdono, gli eventi cifrati sono illeggibili, per te e per noi.
• Non possiamo leggere memorie, note, Timeline, CodeMap, cronologia delle modifiche o chat. Non sappiamo che tipo di evento sia né a quale file si riferisca.
• Non carichiamo codice né file dell'indice, in nessun piano.
• Non rendiamo i messaggi diretti privati rispetto al team: vedi il passo 6.
• Il servizio di pianificazione e chat è ospitato da noi e non ha connettori. Un'azienda che vuole integrazioni gestisce il proprio hub, <code>codelux-hub</code> (incluso in Team): esegue le notifiche di Jira, Linear, Asana, Azure Boards, GitHub, GitLab e Slack con token che restano nella tua azienda. Il modello di DPA, il questionario di sicurezza e la guida al deployment sono nella pagina <a href="/security">Sicurezza</a>; un DPA firmato è disponibile su richiesta.