Sync Your Folder to ChatGPT: the story behind `openai-folder-sync`

created: venerdì, ago 29, 2025

Tempo fa mi capitava sempre lo stesso problema: avevo un sacco di note, specifiche e documenti markdown sul mio portatile, ma quando aprivo ChatGPT e facevo domande su di essi il modello ovviamente non sapeva che esistessero. Copiare e incollare i file era tedioso; caricarli manualmente uno a uno non era molto meglio. Così ho costruito una piccola CLI che fa la parte noiosa per me: openai-folder-sync, uno strumento da riga di comando che sincronizza una directory locale con uno store vettoriale OpenAI, così quei file diventano contesto ricercabile per ChatGPT.

Perché uno store vettoriale?

La funzione di ricerca file di OpenAI si basa su uno store vettoriale. Aggiungi file a uno store, vengono processati in embedding, e gli assistant (o ChatGPT tramite strumenti collegati) possono recuperare e fondare risposte usando quei file. È un modello pulito, ma presuppone che ti ricorderai di caricare e mantenere il tuo set di file. Un passaggio di sincronizzazione — che rispecchia una cartella di cui già ti occupi — è più vicino a come lavoriamo quotidianamente.

Cosa fa lo strumento

openai-folder-sync esegue la scansione di una directory sulla tua macchina, filtra i file per estensione e li invia a uno store vettoriale esistente. Puoi eseguirlo una volta per popolare uno store, oppure integrarlo nella tua routine (ad esempio, un job cron) per mantenere aggiornata la tua base di conoscenza. C’è anche un interruttore per includere i metadati git (branch e commit) nel contenuto caricato, così quando ChatGPT cita qualcosa sai esattamente da quale versione proviene.

Rispecchia una cartella locale in uno Store vettoriale
Supporta il filtraggio per estensione (es. md,txt,pdf)
Provenienza git opzionale (--git-info)
Può essere scriptato o eseguito ad-hoc

Repo: https://github.com/JensWalter/openai-folder-sync

Installazione

È scritto in Rust e si installa tramite Cargo:

cargo install --git https://github.com/JensWalter/openai-folder-sync.git

Cargo compilerà e posizionerà il binario openai-folder-sync nel tuo PATH.

Utilizzo

Ti servirà una chiave API di OpenAI e un ID di uno store vettoriale esistente (appare come vs_…). Poi punta la CLI alla tua cartella:

openai-folder-sync \
  --vector-store 'vs_ABCDEFGHIJK' \
  --local-dir '/Users/jens/tmp/wiki/content' \
  --extensions md

Preferisci eseguirlo tramite Cargo durante lo sviluppo?

cargo run -- \
  --vector-store 'vs_ABCDEFGHIJK' \
  --local-dir '/Users/jens/tmp/wiki/content' \
  --extensions md

La maggior parte dei flag può essere impostata anche tramite variabili d’ambiente:

export OPENAI_API_KEY=sk-...
export VECTOR_STORE=vs_ABCDEFGHIJK
export LOCAL_DIR=/Users/jens/tmp/wiki/content
export EXTENSIONS=md,txt,pdf
export GIT_INFO=true

openai-folder-sync

Common flags
  --vector-store / VECTOR_STORE – ID dello store di destinazione
  --local-dir / LOCAL_DIR – cartella da sincronizzare
  --extensions / EXTENSIONS – elenco separato da virgole
  --git-info / GIT_INFO – includere i metadata git (true|false)
  --help – mostra tutte le opzioni

Come si integra con ChatGPT

Una volta che i file sono in uno store vettoriale, ChatGPT (o le tue app che usano l’Assistants API) possono recuperare estratti rilevanti da quei file mentre rispondono alle tue domande. Questo significa che puoi chiedere cose come “Cosa diceva la proposta sulla timeline di migrazione?” e il modello tirerà il contesto rilevante dai tuoi documenti sincronizzati — niente copia-incolla richiesto. La tua cartella diventa effettivamente una base di conoscenza viva.

Consigli e avvertenze

Scegli le estensioni in modo mirato. Parti dai formati che usi effettivamente — md, txt, magari pdf. Questo mantiene la elaborazione veloce e il recupero mirato.
Crea prima lo store vettoriale. Lo strumento si aspetta un ID di store; creane uno tramite l’API o la dashboard, poi passa quell’ID alla CLI.
Usa le informazioni git per la provenienza. Se sincronizzi da un repo, abilitare –git-info tagga il testo caricato con i metadata del commit, rendendo le risposte più facili da fidare e tracciare.
Escludi il rumore. Considera di tenere gli artefatti di build, node_modules o i file temporanei fuori dalla directory di sincronizzazione, o aggiungili a .gitignore se ti affidi ai metadata git.

Esempio di workflow

Create uno store vettoriale per ogni dominio di conoscenza (es., “Company Wiki”, “Research Notes”).
Point openai-folder-sync alla cartella locale corrispondente.
Eseguire come parte della tua routine di scrittura (per me: dopo il push su main).
Fare domande a ChatGPT e lasciare che il retrieval faccia il lavoro pesante.

Roadmap

Al momento non ho ulteriori piani per questo strumento. Se pensi che manchi qualcosa, apri pure un issue o una PR.

⸻

Se vuoi provarlo, il repository include i dettagli di installazione e utilizzo oltre all’help. L’ho costruito per rendere più semplice il mio flusso di lavoro; se ti evita qualche maratona di copia-incolla e aiuta ChatGPT a rispondere dai tuoi documenti reali, è una vittoria. Buona sincronizzazione!