🇮🇹 Italiano | 🇬🇧 English

agentic-web-clipper

Web clipper agentico: trasforma qualsiasi URL in Markdown pulito e pronto per Obsidian, unendo un estrattore deterministico (Chrome headless + Defuddle) a un agente LLM che recupera i contenuti che l'estrattore scarterebbe per errore.

Agentic web clipper for Obsidian — turn any URL into clean, LLM-ready Markdown. Full documentation available in English.

Un toolkit Node.js agnostico (nessun selettore per-sito) e portabile (copiabile in qualsiasi progetto/vault, Windows·macOS·Linux, senza modifiche al codice). Riproduce — e migliora — l'Obsidian Web Clipper ufficiale, con una pipeline ibrida a due livelli.

Cos'è

• Livello 1 — deterministico (clipper/clip.mjs): renderizza la pagina con Chrome, chiude i cookie, espande accordion/tab, estrae il contenuto principale, aggiunge il livello commerciale da JSON-LD, e scrive un .md con frontmatter — più un sidecar dei blocchi che ha scartato.
• Livello 2 — ibrido (skill /clip): un agente giudice decide quali blocchi scartati sono davvero on-topic e li ricuce nel .md; un controllo qualità (lint + agente ispettore) verifica la completezza. I giudizi sono in cache, così i re-clip costano quasi nulla.

Struttura del repo

clipper/            Il tool. Copia QUESTA cartella nel tuo progetto per usarlo.
  clip.mjs            estrattore deterministico (CLI)
  merge-candidates.mjs  merge dei recuperi del giudice (CLI)
  lint-clip.mjs / score-clip.mjs  QA e scoring (CLI)
  ocr.mjs             scaffold OCR (non ancora cablato)
  README.md           ← GUIDA COMPLETA (installazione, uso, configurazione, portabilità)
  ROADMAP.md          changelog vivo
.claude/            Integrazione Claude Code (livello ibrido)
  skills/clip/SKILL.md      orchestrazione della pipeline /clip
  agents/clip-judge.md      agente giudice (keep/discard)
  agents/clip-inspector.md  agente ispettore di completezza

Avvio rapido

cd clipper
npm install
node clip.mjs "https://example.com/una-pagina"
# → scrive ../raw/<Titolo>.md

La documentazione completa (installazione, uso, configurazione, sicurezza, portabilità, troubleshooting) è in clipper/README.md.

Installazione con Claude Code

Il livello ibrido (giudice + QA) gira dentro Claude Code: la skill /clip orchestra la pipeline, gli agenti fanno il giudizio e l'ispezione.

Prerequisiti: Node.js ≥ 22.12, Google Chrome installato, Claude Code.

1. Clona il repo e installa le dipendenze:

   git clone https://github.com/3stelth/agentic-web-clipper.git
   cd agentic-web-clipper/clipper
   npm install

2. Apri la cartella del repo con Claude Code: la skill /clip e gli agenti (clip-judge, clip-inspector) in .claude/ vengono rilevati automaticamente — nessuna registrazione manuale.

3. In alternativa, per usarlo dentro un progetto esistente: copia la cartella clipper/ e il contenuto di .claude/ (skills/clip/ + agents/) nel tuo progetto, poi cd clipper && npm install.

Uso. In Claude Code digita:

/clip <url>            # pipeline completa: estrazione + giudice + merge + QA

Oppure, solo livello deterministico da terminale (zero LLM, zero costo):

node clipper/clip.mjs <url>

Integrazione con Obsidian

Il clipper può sostituire il Web Clipper ufficiale di Obsidian. Un vault Obsidian è una normale cartella: basta far scrivere il clipper dentro il vault e la nota compare da sola — Obsidian indicizza automaticamente i file esterni, nessun passo di "import".

Configurazione. Crea clipper/clipper.config.json (copiando clipper.config.example.json) con outDir puntato a una cartella del vault:

{
  "outDir": "C:/Users/tu/Documents/MioVault/Clippings"
}

In alternativa usa il flag --out <dir> o la variabile d'ambiente CLIP_OUT_DIR (precedenza: --out > CLIP_OUT_DIR > config > default ../raw).

Flusso. /clip <url> in Claude Code → il .md con frontmatter (title, source, author, published, created, tags) appare nel vault, esattamente come col Web Clipper ufficiale — ma con la pipeline ibrida: contenuti recuperati dal giudice, QA automatico di completezza.

Differenze rispetto al Web Clipper ufficiale: gira headless senza browser aperto, espande accordion/tab collassati, cattura i dati commerciali da JSON-LD (## Dati commerciali), e recupera via agente i blocchi scartati per errore dall'estrattore.

Sicurezza

Il tool renderizza pagine non fidate e adotta difese di default: sandbox di Chrome attivo, solo URL http/https, escaping robusto del frontmatter, cap difensivi contro il DoS. Dettagli nella sezione Sicurezza di clipper/README.md.

Per segnalare una vulnerabilità vedi SECURITY.md.

Licenza

MIT.

---

Obsidian, Defuddle, Puppeteer e i prodotti citati appartengono ai rispettivi titolari. Progetto indipendente, non affiliato.