In questo articolo

🔍 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.

La carta d'identità del repo
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 ↗

Fotografia al 28 settembre 2026: progetto attivo di LangChain, ~4.4k stelle e trazione crescente.

⚙️ 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.

Terminale · generazione della prima wiki
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 ↗

La primera generazione richiede ~2-5 minuti a seconda della dimensione del repo e della quota API.

🔄 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.

GitHub Actions · openwiki-update.yml
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 ↗

Copia-incolla nel tuo .github/workflows/ e non pensi più alla wiki: CI la mantiene fresca ogni push.

🤖 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).

Claude Code MCP config · leggere la wiki dal sistema
{
  "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

MCP setup · README ↗

Una volta configurato, l'agente può chiedere alla wiki senza che tu glielo dica esplicitamente.

📚 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.

Struttura di un articolo OKF in OpenWiki
Create a new repositoryOwner * / Repository name *your-username/claude-marketplaceDescription (optional)My personal Claude Code marketplacePublicAnyone on the internet can see this repository.PrivateYou choose who can see and commit to this repository.Create repository

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.

Due approcci al contesto dell'agente

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.