QuickStart — VibeCoded Orchestrator pronto in 10 minuti

Knowledge orchestrator local-first per workflow di coding AI. Open source. Gira interamente sulla tua macchina.

Cos'è VCO?

VibeCoded Orchestrator (VCO) gira in background mentre lavori in VS Code con la estensione Claude Code. Indicizza la tua knowledge, il codice e le chiamate ai tool, dando a Claude memoria persistente e retrieval consapevole del codice — senza cambiare come lavori.

VCO funziona con qualsiasi client Claude Code che legga la cartella .claude/ del progetto. VS Code con l'estensione Claude Code è il target principale; la CLI standalone e altri client compatibili funzionano allo stesso modo.

Open source (AGPL-3.0). Nessuna dipendenza dal cloud.

Prerequisiti

Lo script first-install.* rileva ciò che manca e propone di installarlo. Su Linux ti chiede sudo per installare i pacchetti di sistema.

Step 1 — Prendi il codice

A. Clona il repo (consigliato per chi sviluppa)

cd ~/dev    # or wherever you keep your code
git clone https://github.com/hotak92/vibecoded-orchestrator.git
cd vibecoded-orchestrator

B. Scarica un archive di release (consigliato per chi installa)

Ogni release pubblica un archive completo per OS su Releases: vibecoded-orchestrator-0.2.21-linux-x64.tar.gz, vibecoded-orchestrator-0.2.21-macos-arm64.tar.gz, vibecoded-orchestrator-0.2.21-windows-x64.zip. Ogni archive contiene launcher + CLI vco + binario vct-hub + stack Python MCP + template (agent / skill / hook) + script di install — niente git clone necessario. Estrai e doppio-click su first-install.{sh,command,desktop,bat}. Ogni archive ha un sidecar .sha256; i binari del launcher e dell'hub sono SLSA-attestati:

gh attestation verify <downloaded-binary> --repo hotak92/vibecoded-orchestrator

Step 2 — Esegui l'installer

Un solo comando. L'installer rileva le dipendenze mancanti, chiede conferma prima di installare pacchetti di sistema e prepara il venv Python dell'orchestrator e i container.

bash first-install.sh

(oppure doppio click su first-install.desktop dal file manager — alcuni DE richiedono di abilitare prima "Esegui file di testo eseguibili")

L'installer impiega 5–10 minuti più i download iniziali delle immagini (~5 GB).

Step 3 — Avvia l'orchestrator

L'installer non avvia il launcher in automatico. Quando first-install stampa [install] done, avvia manualmente la GUI del launcher dalla stessa cartella in cui hai eseguito l'installer. Da lì registri progetti, gestisci secret e controlli lo stato dei servizi.

cd ~/dev/vibecoded-orchestrator   # the directory you cloned into
bash start-launcher.sh

Oppure doppio click su start-launcher.desktop dal file manager.

Si apre una finestra GUI nativa.

Step 4 — Segui il wizard

Al primo avvio, l'OnboardingWizard ti guida in 5 step. Il wizard parte automaticamente; gli avvii successivi vanno dritti alla tua library.

4a. Welcome (step 1 di 5)

Una breve intro a cosa fa VCO. Clicca su Next → per continuare.

4b. System (step 2 di 5)

Il wizard sonda il sistema: versione di Python, runtime container (Docker o Podman), GPU, RAM/VRAM disponibili. La maggior parte degli utenti vede tutti i tick verdi. Se manca qualcosa, il wizard ti dice cosa installare. Clicca su Next → quando tutto il necessario è stato rilevato.

4c. Containers (step 3 di 5)

Il wizard installa il venv Python di VCO nel tuo repo sorgente. Il path di install è auto-rilevato dalla cartella di clone, non selezionabile dall'utente. La pagina lo mostra in sola lettura: "Installing into /your/clone/path (your source repo)".

Sonda anche i servizi condivisi e propone di avviarli se mancano:

• Weaviate — vector DB per KG e ricerca code graph
• Ollama — inferenza LLM locale ed embedding
• code_embed (opzionale, solo GPU) — CodeSage-Large-v2 per embedding di codice di qualità superiore

Se i servizi sono già up (es. hai un altro install di VCO sulla stessa macchina), il wizard li riusa — stessi dati, niente doppio install. Il toggle "Use separate containers for this install (advanced)" è per power user che vogliono isolamento totale.

La posizione dei volumi container è mostrata per trasparenza. Clicca su Install quando sei pronto, conferma nel modal, poi Next → quando i servizi sono attivi.

4d. First project (step 4 di 5)

Qui registri il tuo primo progetto. Inserisci:

• Project name: un'etichetta descrittiva (es. test-project)
• Project folder: path assoluto a una cartella di progetto esistente. Clicca su Browse… per sceglierla.
• (opzionale) GitHub token: un PAT in sola lettura (scope public_repo) dà al launcher 5000 richieste/ora per recuperare versioni più recenti dell'orchestrator; senza, hai 60/ora anonime.

Clicca su Finish. Il wizard registra il progetto, crea le sue collection KG e code-graph in Weaviate, e scrive lo stato per-progetto in ~/.vct/launcher.db. Subito dopo, il launcher fa partire tre task in background sul progetto appena registrato: code-graph build, KG sync (knowledge/**/*.md + docs/**/*.md → Weaviate via kg-sync --all), e KG summaries (generate-kg-summary.py per ogni nodo, fallback claude CLI → Ollama → ANTHROPIC_API_KEY → silent skip). Ognuno mostra un banner sotto l'header del progetto: pending / running / failed restano visibili, success / skipped si auto-nascondono dopo 30 s. I tre bottoni in alto a destra (Re-build code graph, Re-sync KG, Re-build KG summaries) li rilanciano on-demand. Se il launcher crasha a metà run, al boot successivo le righe running vengono marcate failed con un messaggio "launcher crashed mid-run; click Retry to re-run" — niente silent re-spawn.

4e. OpenAI key (step 5 di 5, opzionale)

Step skippabile per chi vuole usare OpenAI come provider di embedding. Default VCO: locale — qwen3-embedding:0.6b per il testo (1024-dim, via Ollama) e codesage-large-v2 per il codice (GPU, 2048-dim; fallback automatico in catena su qwen3-embedding:0.6b → jina-embeddings-v2-base-code se il servizio code-embed o la GPU non sono disponibili). Per usare OpenAI: incolla la API key (input password-masked), clicca Validate (probe gratuito su /v1/models, niente token consumati e niente entry di billing), e spunta "Use OpenAI as the default embedding provider for new projects". La chiave viene salvata nel keychain dell'OS; il launcher la ri-valida ad ogni avvio e fa fallback ai modelli locali se diventa invalida, ripristinando OpenAI quando ritorna disponibile. Click Finish (oppure Skip).

Step 5 — Verifica che tutto funzioni

Dopo Finish vieni portato sulla home Library con il nuovo progetto in lista. Clicca sulla card del progetto per aprirne la dashboard.

Ora apri Claude Code dalla cartella del progetto:

cd ~/dev/test_project
claude

(oppure apri la cartella in VS Code con l'estensione Claude Code installata)

Impostazioni di sessione consigliate per Claude Code

Prima della tua prima sessione in questo progetto, apri la command palette di Claude Code (Cmd/Ctrl + K) e configura la sezione Model. L'impostazione corretta dipende dal modello che stai usando:

• Opus 4.6 / Sonnet 4.6 e precedenti: Effort → Max, Thinking → Off. Su questi modelli il thinking a budget fisso aggiunge latenza senza guadagni misurabili di retrieval quando gli hook di VCO iniettano già contesto pesante per turno. Effort Max dà al modello margine per ragionare su quel contesto correttamente.
• Opus 4.7: Effort → high per default — è la scelta giusta per la cura della KG, le query sul code-graph e il grosso dei workflow VCO. Usa xhigh solo quando serve creatività (brainstorming, design generativo, esplorazione di alternative): su task tecnicamente complessi xhigh tende a introdurre più allucinazioni di high. Il toggle Thinking è un no-op su 4.7 — lascialo stare. Perché non Max qui: 4.7 usa thinking adattivo governato dal livello di effort, quindi Max spesso consuma più budget di thinking di quanto i workflow VCO ne traggano realmente beneficio.

Modifica un file qualsiasi nel progetto. Gli hook dell'orchestrator scattano in background, in silenzio — niente toast o riga di log nella finestra del launcher. Cosa fanno:

• Knowledge Graph (continuo, hook-driven): quando scrivi o modifichi un file knowledge/**/*.md, il markdown viene auto-chunkato, embeddato col modello configurato e sincronizzato in una collection Weaviate (nome di default: <ProjectName>_KnowledgeGraph). Claude Code può cercarci subito via hybrid_search dal MCP weaviate-kg. La stessa KG può essere marcata shared (altri progetti leggono+scrivono) o archive (sola lettura) dal tab KG / Codegraph del progetto.
• Code Graph (incrementale + rebuild completo manuale): indicizza ogni modulo / classe / funzione / API / chiamata cross-service del progetto. L'hook post-file-edit lancia un update incrementale per ogni file di codice modificato (debounced 120s, gira code-graph-incremental.sh in background — supporta .py, .ts/.tsx, .js, .rs, .go, .java, .cpp, .rb, .cs, ecc.). Per un re-index completo — es. dopo un refactor grosso o quando importi un progetto esistente per la prima volta — usa il bottone Re-build code graph per-progetto oppure .claude/scripts/code-graph-analyze . dalla root.
• Altri hook: ruff e pyright sui write Python, scanner credenziali su ogni file, cost tracker per sessione Claude, il nuovo kg-update-nudge che ti ricorda di scrivere nodi KG dopo 150k token di lavoro non registrato. Tutti silenziosi a meno che qualcosa non richieda la tua attenzione.

Due posti per gestire KG/Codegraph: per-progetto (binding) vs. machine-wide (accesso)

Il launcher espone la configurazione KG/Codegraph in due posti distinti, ognuno per un compito diverso:

• Tab per-progetto — Project → KG / Codegraph. Qui configuri il binding per il progetto attivo: ruolo (primary / shared / archive), nome collection Weaviate, modello di embedding, URL Weaviate. La maggior parte degli utenti ci mette mano solo il primo giorno; il wizard pre-compila default sensati. Coperto nello Step 6.
• Route top-level — /kg e /codegraph. Sono dashboard di accesso cross-progetto. Ognuna mostra come card ogni collection KG Weaviate o code-graph index presente sulla macchina, con un access badge (READ / WRITE / NONE) che descrive l'accesso del progetto attivo, più i bottoni Browse e Access… Un badge shared separato marca le collection condivise tra progetti. Usa queste dashboard quando vuoi che il progetto A legga la KG di B, es. una collection "personal notebook" condivisa che più progetti popolano. Nell'uso quotidiano, gli agent leggono la collection giusta automaticamente in base al binding del progetto, quindi quasi mai serve aprirle.

Flow comuni

• Cambiare la collection di un progetto: tab del progetto → sotto-tab KG / Codegraph → modifica binding → Save.
• Far leggere a A la KG di B: top-level /kg → trova la card di B → Access… → grant.

Step 6 — Tour della configurazione (post-wizard)

Una volta registrato il progetto, clicca sulla sua card nella Library home per aprire la pagina settings per-progetto. Ogni progetto ha la sua configurazione su sette tab.

Tab Agents — cosa gira nel progetto

Il launcher porta 45 agent Claude Code bundle (code-explorer, coder, planner, gui-tester, doc-organizer, ecc.). Dal tab Agents abiliti/disabiliti ogni agent per-progetto e registri quelli custom.

Tab Skills — slash command

Stesso pattern degli Agents ma per gli slash-command skill (/architect, /tdd, /api-designer, /security-reviewer, ecc.). 52 skill bundle.

Tab Hooks — automazioni che scattano a ogni tool call

Registry hook per-progetto. 27 hook bundle scattano automaticamente: file edit sincronizzati a KG, controlli di sintassi sui write, scanner credenziali, KG-update nudge ogni 150k token, e altro. Disabilita singoli hook per-progetto se uno è rumoroso in un certo workflow.

Tab Permissions — allow/deny list per i tool degli agent

Per default gli agent hanno accesso ampio; restringi per i progetti sensibili. 5 tipi di regola distinti danno controllo fine:

Tab Secret refs — env var per-progetto (GITHUB_TOKEN, ecc.) ⭐

La maggior parte dei workflow ha bisogno almeno di GITHUB_TOKEN per le operazioni sui repo e magari OPENAI_API_KEY se usi OpenAI come fallback. Il launcher tiene traccia di quali chiavi servono al progetto; i valori vivono nel keychain dell'OS, non in nessun file VCO. Il launcher conserva solo il riferimento, mai il plaintext.

Tre scope

• Per-project: solo i moduli di questo progetto possono leggerlo. Il form ha un dropdown progetto + KEY + valore. Scegli il progetto dal dropdown (compaiono solo quelli registrati; clicca su ↻ per il refresh). Usalo per token specifici di un progetto, es. un PAT GitHub di progetto.
• Shared (this user): tutti i tuoi progetti possono leggerlo. Form con solo KEY + valore (niente picker). Usalo per token condivisi, es. una chiave OpenAI personale.
• Global (this machine): ogni progetto sulla macchina può leggerlo. Stesso form. Usalo per cose machine-wide tipo una license key.

Read order (come i moduli trovano un secret)

Quando un modulo nel progetto P chiede un secret K, il launcher controlla in ordine:

1. Bag per-progetto di P (i secret di P)
2. Collection shared (i secret shared dei tuoi altri progetti)
3. Global (machine-wide)

Vince il primo hit. Un modulo in P non vede mai il bag per-progetto di un altro progetto — è la garanzia di isolamento.

Il checkbox "Sensitive"

Default ON, e quasi sempre quello che vuoi.

• Sensitive ✓ (checked): il launcher si rifiuta di mostrare il valore ovunque, anche i preview mascherati sono bloccati. Vedi solo i badge set / not set. Per token, API key, password. Consigliato per qualsiasi cosa segreta.
• Sensitive ☐ (unchecked): il launcher può mostrare un preview mascherato (es. gh***xx) negli audit log e nel pannello. Solo per stringhe di config non segrete (URL, username, nomi modello) che vuoi verificare a colpo d'occhio nei log. Non togliere il check sui token.

Lifecycle Set / Unset / Reactivate / Remove

Ogni secret registrato ha quattro operazioni:

• Set / Update: scrive un valore nel keychain e marca l'entry come attivo.
• Unset: marca l'entry come inattivo ma tiene il valore al sicuro nel keychain. Utile per la rotazione: pausa senza perdere il valore, valida lo stato nuovo, poi riattiva. Il valore non viene mai restituito ai reader mentre è inattivo.
• Reactivate: appare come bottone one-click sugli entry inattivi. Riporta l'entry ad attivo usando il valore salvato, senza re-inserire. Usa "Set as new value" se vuoi sostituire il valore salvato.
• Remove: elimina la riga registry E pulisce il keychain. Il modal di conferma suggerisce "Use Unset instead if you just want to clear the current value". Scegli Remove solo se non userai più questa chiave.

Tab KG / Codegraph bindings ⭐

Decide quale collection Weaviate colpiscono hybrid_search e le query code-graph del progetto. Il wizard pre-compila default sensati ma verifica al day one — setting sbagliato → confusione "non trovo i miei appunti".

• Role: primary — questo progetto possiede la KG; gli altri possono leggere ma non scrivere. Default per i nuovi progetti.
• Role: shared — più progetti scrivono in una sola KG (es. una "personal notebook" condivisa). Utile per la sintesi cross-progetto.
• Role: archive — sola lettura; il progetto cerca nella KG ma non aggiunge mai.
• Embedding model: qwen3-embedding:0.6b per il testo (default; in alternativa openai-text-embedding-3-small se hai configurato la chiave OpenAI nel wizard o nelle Preferences). Per il codice: codesage-large-v2 (GPU, default), che fa fallback in catena su qwen3-embedding:0.6b → jina-embeddings-v2-base-code quando il servizio code-embed o la GPU non sono raggiungibili.
• Codegraph prefix: namespace per le entità code-graph del progetto. Default è lo slug del progetto, di solito va bene.

Tab Settings — metadata + note env var del progetto

Modifica nome del progetto, vedi folder/host/created-at, e (importante) tieni una lista solo-note delle env var che i tuoi agent si aspettano. Comodo per onboardare un teammate senza passargli i valori.

Route top-level che vale la pena conoscere

Oltre ai tab per-progetto, la sidebar di sinistra del launcher ha una sezione SYSTEM con queste route top-level:

Services — gestisci i container condivisi

Avvia/ferma il vector DB Weaviate, il server LLM Ollama (embedding + summarization) e il servizio code_embed da una sola pagina. Il launcher rileva i servizi già attivi (es. avviati da un altro install VCO o da un precedente podman-compose up -d) e li tratta come external · adopt, niente doppia gestione.

MCP servers — la dashboard delle capability di Claude

Mostra ogni server Model-Context-Protocol registrato con Claude Code. Il launcher registra 4 server abilitati di default che vedi anche da claude mcp list: weaviate-kg (Knowledge Graph + Code Graph, query semantiche con hybrid_search / search_code_graph), search (paper accademici via OpenAlex + arXiv tramite search_papers), coordination (note di team locali KG-backed) e playwright (browser automation, registrato via npx -y @playwright/mcp@latest — opt-out con VCT_SKIP_PLAYWRIGHT=1). Ollama gira come infrastruttura di embedding (consumata da weaviate-kg + code-embedding service), non come tool MCP esposto a Claude. Da qui aggiungi anche server MCP custom.

Altre route

Cose da sapere che non sono nella GUI

Troubleshooting

Runtime container rilevato ma non attivo

Hai Docker o Podman installato ma il daemon non è partito.

# Linux Podman:
systemctl --user start podman.socket

# Linux Docker:
sudo systemctl start docker

Python è 3.10 o più vecchio

VCO richiede Python 3.11+. L'installer propone di installare Python 3.12 col tuo package manager (apt / dnf / pacman). Puoi anche installarlo via pyenv prima di lanciare l'installer.

16 GB di RAM e warning "OOM" durante il caricamento modelli

Il modello di KG-summary Ollama di default (qwen3.5:9b) ha bisogno di ~24 GB effettivi; su sistemi a 16 GB il launcher fa fallback automatico a gemma4:e4b. Per i code embedding, la catena di fallback codesage-large-v2 → qwen3-embedding:0.6b → jina-embeddings-v2-base-code scatta da sola se il servizio code-embed o la GPU non sono raggiungibili. Per forzare il backend più leggero, imposta CODE_EMBED_BACKEND=ollama.

"Could not connect to localhost" al lancio

Il frontend del binario launcher bundle è mancante o rotto. Fix:

bash scripts/build-bundled-launcher.sh

poi riavvia. La defense a 4 layer del build evita che ricapiti su build fresche.

Per altro, vedi KNOWN_ISSUES.md e INSTALL_RECOVERY.md.

Prossimi passi

• Prova un workflow vero: apri uno dei tuoi progetti reali in VS Code con Claude Code, registralo dal launcher, e guarda l'orchestrator popolare KG e code graph mentre lavori per un'ora.
• Leggi la User Guide — spiega ogni tab nel launcher.
• Metti una star al repo GitHub e segui le Discussions. Le prime 100 stelle sono la parte dura.
• Trovato un bug? Apri un'issue. Vuoi una feature? Apri una Discussion sotto "Ideas".