In questo articolo
- 🔍 Cos'è OpenWiki: documentazione strutturata per (e dai) modelli di linguaggio
- ⚙️ Come funziona: scansione del repo → sintesi LLM → wiki OKF
- 🔄 Aggiornamento automatico: CI trigger, wiki freschi, zero latenza per l'agente
- 🤖 Uso con agenti: come un agente consulta la wiki e perché non è invisibile
- 📚 Open Knowledge Format: il linguaggio comune fra wiki e modelli
- 🏢 Perché è interessante, per sviluppatori e PMI
- ⚠️ I limiti da conoscere prima di adottarlo
- ✅ Da dove partire
🔍 Cos'è OpenWiki: documentazione strutturata per (e dai) modelli di linguaggio
OpenWiki è una CLI TypeScript che scansiona il tuo repo, estrae documenti, commenti di codice e file markdown, li sintetizza via LLM, e produce una wiki che vive in Open Knowledge Format (OKF) — uno schema Google Cloud che faccia per la conoscenza ciò che JSON Schema fa per i dati: articoli, concetti, relazioni, tag, tutto dichiarativo e parsabile da un modello.
Non è wiki per umani che leggono via browser: è formato interchange tra codebase e agenti. La wiki vive nel repo (cartella openwiki/), è versionata nel git, e quando un agente ha bisogno di capire «dove vive la business logic di fatturazione?» o «quali sono i vincoli di concorrenza sulla cache?», interroga la wiki locale — nessun fetch esterno, zero latenza. LangChain lo ha pensato per i loro prodotti (langgraph, deepagents, LangSmith), ma è applicabile a qualunque stack: Python, .NET, Node.js, Go, non importa; il sorgente lo legge la CLI, la wiki è formato agnostico.
repo langchain-ai/openwiki linguaggio TypeScript · licenza MIT · v0.5.0 (luglio 2026) piattaforma npm i -g openwiki · Python/Node/Go/Go agnostico cosa CLI che genera wiki OKF per agenti di coding aggiorna CI/GitHub Actions / GitLab CI — post-merge automatico formato Open Knowledge Format (Google Cloud), JSON+YAML contesto Locale, nessun upload — file vive nel repo
Repo ufficiale · langchain-ai/openwiki ↗
⚙️ Come funziona: scansione del repo → sintesi LLM → wiki OKF
Il ciclo è semplice, ma il risultato è sofisticato. La CLI parte da openwiki --init, chiede il modello e l'API key (supporta OpenAI, Anthropic, Ollama locale, OpenRouter — qualunque provider che espone la API standard), poi scansiona il repo cercando file markdown, docstring, commenti strutturati e file code in lingue supportate. Non scarica niente da internet — tutto ciò che vede è nel tuo repo.
Per ogni concetto trovato (funzione, modulo, pattern, tabella database), invia al modello una richiesta sintetica: «Riassumi questo artefatto e le sue dipendenze, estrai i tag tematici, collega ai concetti correlati che ho trovato finora». Il modello risponde con struttura OKF — nome, descrizione, campi tipati, relazioni — non prosa, ma dichiarazione. La wiki finisce in openwiki/ e la lista master vive in openwiki/manifest.json. A questo punto, commit e push, e la wiki è versionata insieme al codice.
npm install -g openwiki
cd ~/code/mio-progetto
openwiki --init
Model? claude-3-5-sonnet
API key? sk-ant-...
# Scanning: 47 TypeScript files, 12 markdown docs, 3 SQL files
# Summarizing 134 concepts...
# Writing openwiki/*.md (OKF format)
git add openwiki/ && git commit -m 'chore: initial wiki generation'
git push
ls openwiki/
api-routing.md database-schema.md auth-flow.md [...]Quickstart · README ufficiale ↗
🔄 Aggiornamento automatico: CI trigger, wiki freschi, zero latenza per l'agente
Dopo l'init, il valore vero di OpenWiki vive negli aggiornamenti automatici. La CLI integra workflow per GitHub Actions, GitLab CI e Bitbucket Pipelines: copi un YAML nel tuo repo, e ogni merge su main triggeRa un openwiki --update. Non ricrea la wiki da zero (sarebbe costoso), ma legge la storia del commit (cosa è stato modificato), esamina i file deltaici, aggiorna i concetti toccati e ri-serializza solo gli artefatti che sono cambiati. La wiki vive nel repo, è committata, e non importa quale branch l'agente consulta: la wiki che vede è quella del codice che sta leggendo.
Questo è il design che rende OpenWiki diverso da un README statico o persino da documentazione Sphinx/Docusaurus: l'agente non fa una ricerca su Google Cloud, non interroga un'API remota — la wiki è locale e sincronizzata con il codice. Una PR cambia un endpoint? La wiki si aggiorna nello stesso merge commit. L'agente che lavora sulla PR successiva vede già la documentazione nuova. Niente sync lag, niente versioning hell.
name: OpenWiki Update
on: [push]
jobs:
wiki:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: {fetch-depth: 0}
- uses: actions/setup-node@v4
with: {node-version: '20'}
- name: Generate wiki
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
npm install -g openwiki
openwiki code --update --print
- name: Create PR
uses: peter-evans/create-pull-request@v5
with:
branch: openwiki/update
title: 'chore: update wiki from main'
commit-message: 'Update wiki from latest commits'Workflow template · documentazione ↗
🤖 Uso con agenti: come un agente consulta la wiki e perché non è invisibile
Qui il disegno diventa interessante. OpenWiki genera la wiki in OKF, ma non ha una HTTP API — non c'è un server che l'agente interroga. La wiki vive nel filesystem. Quindi: o l'agente ha il repo clonato localmente (il caso di Claude Code, Codex, Cursor), oppure la legge via MCP (Model Context Protocol — OpenWiki lo supporta nativemente), oppure la incorpori nel prompt di sistema staccando le sezioni rilevanti. In tutti i casi, ==la wiki non è invisibile all'agente == — l'agente sa che esiste e può consultarla consapevolmente.
Questo è diverso da un vector database RAG dove l'agente non sa quanti documenti ha recuperato o da che filtri. Qui la wiki è fronte-stage: un agente ben progettato inizia dicendo «Sto leggendo la wiki di questo repo, la struttura è [X], i concetti core sono [Y], fammi iniziare da [Z]». E se la wiki è sbagliata, incompleta o stale — magari il repo è stato refattorizzato ma nessuno ha rieducato la wiki — l'agente se ne accorge e può comunicarlo (o correggere e faire una PR).
{
"mcpServers": {
"openwiki": {
"command": "openwiki",
"args": ["mcp", "--repo", "."]
}
}
}
# L'agente ora ha a disposizione:
# - openwiki/search <query>: cerca nella wiki
# - openwiki/get <concept>: legge il documento completo
# - openwiki/concepts: lista tutti i concetti indicizzati📚 Open Knowledge Format: il linguaggio comune fra wiki e modelli
OKF non è venuto fuori dal nulla. Google Cloud l'ha standardizzato per integrare sistemi di knowledge management con LLM: ogni articolo OKF è YAML con campi ben definiti — titolo, slug, categoria, keywords, body in markdown, relazioni ad altri articoli. Non è una struttura bizzarra: è schema coerente che un modello riconosce e sa navigare.
Per gli sviluppatori, questo significa: una volta che la wiki è in OKF, non è bloccata a OpenWiki. Puoi esportarla in Obsidian, processarla con script Python per fare reporting, includerla in una documentazione Docusaurus, o usarla come sorgente per un fine-tuning di un modello locale. La wiki non è un silo; è un artefatto neutrale che il repo possiede e che chiunque può leggere.
Titolo, categoria, keywords e body in markdown: tutto dichiarativo, niente magic string.
🏢 Perché è interessante, per sviluppatori e PMI
Per un developer che adopera agenti (Claude Code, Codex, Cursor + MCP), OpenWiki cambia il rapporto fra agente e codebase. Non dovrai mai staccare il README intero nell'instruction, non dovrai navigare schermate di vector search, non dovrai sperare che l'agente indovini una feature che non è comentata. La wiki è lì, versionata, aggiornata da CI, e l'agente sa dove cercare. È onboarding che si automaintiene: quando un junior arriva, gli stacchi il repo e la wiki è già fresca.
Per una PMI che scala gli agenti nei processi di ingegneria, la storia è più ampia. OpenWiki non solo riduce il carico di mantenere documentazione a mano (la genera la CLI), ma crea un ==artefatto versioned e controllabile == dove governance e contesto convivono. Puoi revisionare una PR della wiki come revisionari una PR del codice. Puoi vedere nella history quando un concetto è stato refattorizzato. Puoi anche usarla come base per un fine-tuning di un modello interno — «questo è il nostro design, questo è il modo in cui leggiamo il codice». La wiki diventa proprietà aziendale strutturata, non segreto nei commenti di un file.
⚠️ I limiti da conoscere prima di adottarlo
Il progetto è attivo e mantenuto (LangChain stessa lo usa internamente), ma la complessità del generare OKF buono da codice vario è reale: una codebase disorganizzata produrrà una wiki disorganizzata. I file senza docstring, i moduli con nomi generici (utils, helpers), i pattern non documentati resteranno invisibili alla CLI. La qualità della wiki dipende dalla qualità della documentazione sorgente più la capacità del modello di inferire pattern — non è magia.
Secondo limite: il costo API. Generare una wiki per una codebase di 100k LoC la prima volta costa — non sempre, ma in funzione di quello che il modello deve sintetizzare. Gli aggiornamenti incrementali sono molto meno costosi (muta solo ciò che è cambiato), ma devi sapere che nel budget dei tuoi agenti entra anche il budget della wiki-generation. LangChain offre lite models e Ollama locale per contenere il costo, ma è un trade-off consapevole.
- Dipende dalla qualità del sorgente: codebase mal documentata → wiki mal strutturata; non c'è soluzione magica per cattive pratiche nel codice.
- Costo API alla prima generazione: richiede N token a modello per sintetizzare il repo; gli update incrementali sono cheaper.
- Occorre un modello: Ollama locale o provider remoto; niente offline senza modello locale già scaricato.
- La wiki è proprietà del repo: deve vivere nel git per mantenersi aggiornata; se ignori openwiki/ nei commit, la perdi.
✅ Da dove partire
Se usi Claude Code (plugin locale) e il tuo repo ha almeno 10-20 file TypeScript/Python con qualche docstring: npm i -g openwiki, copia il workflow GitHub Actions (o GitLab), e genera la prima wiki su un branch di test. Leggi gli articoli OKF generati — puoi correggerli a mano o lanciare --update su sezioni specifiche se serve rifare qualcosa.
Nel panorama più ampio, OpenWiki completa la scala di contesto che descrivo nelle ultime settimane: gli agenti di coding passano da istruzioni monolitiche a wiki ricercabili, a MCP specializzati, a fine-tuning su progetti specifici. OpenWiki è il ponte fra il codice che hai e il contesto che i tuoi agenti riescono a usare. Non è un prodotto, è un cambio di paradigma su come i repo parlano agli agenti — e una PMI che lo adotta oggi riesce a dare agli agenti il contesto corretto molto più veloce di chi legge README e gira con ls -R nel repo.
Staccare il README nell'instruction
- L'agente vede il contesto ma monolitico
- Non cambia senza un nuovo training della conversazione
- Brucia token in ogni messaggio
- Un nuovo agente riprende da zero ogni volta
Wiki OKF da OpenWiki
- L'agente la consulta on-demand
- Aggiornamento automatico da CI
- Richiede token solo per sezioni rilevanti
- Onboarding fresco per ogni agente, ogni volta
Non competitivi: complementari. Il README per umani, la wiki per agenti.
Domande frequenti su OpenWiki
Che cos'è OpenWiki?
È una CLI open source di LangChain che genera automaticamente una wiki di documentazione della tua codebase in Open Knowledge Format (OKF), strutturata per il consumo diretto da LLM e agenti di coding. Scansiona il repo, sintetizza concetti via modello, e produce una wiki che vive nel repo e si aggiorna da CI.
In cosa è diverso da Docusaurus, Sphinx o una wiki Obsidian?
Docusaurus e Sphinx producono HTML per umani da markdown. OpenWiki produce OKF — formato strutturato — per agenti. Obsidian è locale ma manuale. OpenWiki è automatico, versionato nel git, e aggiornato da CI: la wiki rispecchia sempre il codice corrente.
Che cos'è Open Knowledge Format (OKF)?
È uno schema YAML standardizzato da Google Cloud per rappresentare articoli di knowledge — titolo, slug, categoria, keywords, body. Un modello lo riconosce e sa navigarlo. Non è proprietario a OpenWiki: una volta che la wiki è OKF, è portabile a qualunque tool che supporta lo standard.
Quanto costa generare una wiki con OpenWiki?
Dipende dalla dimensione del repo e dal modello. La prima generazione costa N token a modello per sintetizzare i concetti. Gli aggiornamenti incrementali (--update) sono molto più cheap perché toccano solo i file modificati. Supporta Ollama locale, OpenAI, Anthropic, OpenRouter: puoi scegliere il trade-off fra costo e qualità.
L'agente sa automaticamente che esiste una wiki, o devo dirglielo?
Se usi MCP (Model Context Protocol), l'agente ha il tool disponibile automaticamente e può cercarla. Altrimenti dovrai includerla nel prompt di sistema o dirgli esplicitamente di consultarla. OpenWiki non è invisibile: l'agente sa che esiste.
La wiki rimane locale nel repo, o va su un server cloud?
Rimane locale nel repo, versionata nel git. Niente upload, niente server esterno, zero latenza. Se vuoi, puoi hostare la wiki su un sito web, ma quella non è una caratteristica nativa di OpenWiki.
Parliamone
Se questo tema ti riguarda, scrivimi: confrontarsi su codice e AI è sempre tempo speso bene.



