Neo

Trasforma qualsiasi app web in un'API. Non serve un'API ufficiale. Nessuna automazione del browser.

Neo è un'estensione Chrome che cattura passivamente ogni chiamata API che il tuo browser effettua, impara gli schemi e permette all'AI (o a te) di riprodurle direttamente.

Il problema

Gli agenti AI che operano su app web oggi hanno due opzioni, entrambe pessime:

Approccio	Problema
API ufficiali	La maggior parte dei SaaS non ne ha una, o espone solo il 10% delle funzionalità
Automazione del browser	Screenshot → OCR → click. Lento, fragile, si rompe ad ogni modifica dell'interfaccia

Neo è la terza via. Ogni app web ha già una API interna completa — il frontend la chiama ogni volta che clicchi qualcosa. Neo cattura queste chiamate e le rende riproducibili.

v2: Ora con automazione dell'interfaccia utente. Neo v2 aggiunge un livello UI basato sull'albero di accessibilità — snapshot, click, fill, type, press, hover, scroll, select, screenshot, get, wait. Quando un'API esiste, la usa direttamente. Quando non esiste, Neo può guidare l'interfaccia tramite la stessa CLI. Un unico strumento, entrambi i livelli.

Come funziona

Browse normally → Neo records all API traffic → Schema auto-generated → AI replays APIs directly
                                                                      → Or drives UI via a11y tree

1. Cattura (sempre attiva)

L'estensione Chrome intercetta ogni fetch() e XMLHttpRequest — URL, header, corpo della richiesta/risposta, tempistiche, persino quale elemento DOM ha innescato la chiamata.

2. Impara

Esegui neo-schema su un dominio per generare automaticamente la sua mappa API: endpoint, header di autenticazione richiesti, parametri query, struttura della risposta, codici di errore.

3. Esegui

Esegui chiamate API nel contesto della scheda del browser tramite Chrome DevTools Protocol. Cookie, token CSRF, autenticazione di sessione — tutto ereditato automaticamente. Nessuna gestione token necessaria.

Browser supportati

Browser	Tipo	Migliore per
Chrome / Chromium	Browser completo	Cattura API + automazione UI (predefinito)
Lightpanda	Headless (Zig)	Agenti AI, scraping — 11x più veloce, 9x meno memoria

Avvio rapido

git clone https://github.com/4ier/neo.git
cd neo && npm install && npm run build
npm link  # rende `neo` disponibile globalmente

Carica l'estensione:

Apri chrome://extensions
Abilita "Modalità sviluppatore"
Clicca "Carica estensione non pacchettizzata" → seleziona extension/dist/
Naviga su qualsiasi sito — Neo inizia a catturare immediatamente

Lightpanda (headless, nessuna estensione necessaria)

# Installa Lightpanda
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux
chmod +x lightpanda && sudo mv lightpanda /usr/local/bin/

# Configura Neo per usare Lightpanda
# In ~/.neo/config.json:
# { "chromePath": "/usr/local/bin/lightpanda", "browserType": "lightpanda", "cdpPort": 9222 }

neo start    # avvia il server CDP di Lightpanda
neo connect  # collegati
neo open https://example.com
neo snapshot # albero di accessibilità completo

Strumenti CLI

Tutti i comandi passano attraverso una singola CLI: neo <comando>.

Richiede un browser con CDP (Chrome DevTools Protocol) abilitato.

# --- Connessione e Sessioni ---
neo connect [port]                          # Connetti a CDP, salva sessione
neo connect --electron <app-name>           # Scopri automaticamente la porta CDP dell'app Electron
neo launch <app> [--port N]                 # Avvia app Electron con CDP abilitato
neo discover                                # Trova endpoint CDP raggiungibili su localhost
neo sessions                                # Elenca sessioni salvate
neo tab                                     # Elenca target CDP nella sessione attiva
neo tab <index> | neo tab --url <pattern>   # Cambia target della scheda attiva
neo inject [--persist] [--tab pattern]      # Inietta script di cattura Neo nel target

# --- Cattura e Traffico ---
neo status                                  # Panoramica dei dati catturati
neo capture summary                         # Riepilogo rapido
neo capture list github.com --limit 10      # Mostra ID per replay/dettaglio
neo capture list --since 1h                 # Filtrato per tempo
neo capture domains
neo capture search "CreateTweet" --method POST
neo capture watch x.com                     # Live tail (come tail -f)
neo capture stats x.com                     # Analisi metodo/stato/tempo
neo capture export x.com --since 2h > x.json
neo capture export x.com --format har > x.har  # HAR 1.2 per Postman/devtools
neo capture import x-captures.json
neo capture prune --older-than 7d
neo capture gc x.com [--dry-run]            # Deduplica intelligente

# --- Replay ed Esecuzione API ---
neo replay <capture-id> --tab x.com         # Riproduci una chiamata catturata
neo exec <url> --method POST --body '{...}' --tab example.com --auto-headers
neo api x.com HomeTimeline                  # Chiamata intelligente (ricerca schema + auto-auth)

# --- Schema e Analisi ---
neo schema generate x.com                   # Genera da catture
neo schema generate --all                   # Batch su tutti i domini
neo schema show x.com [--json]
neo schema openapi x.com                    # Esporta specifica OpenAPI 3.0
neo schema diff x.com                       # Modifiche rispetto alla versione precedente
neo schema coverage                         # Domini con/senza schema
neo label x.com [--dry-run]                 # Etichette semantiche degli endpoint
neo flows x.com [--window 5000]             # Schemi di sequenza delle chiamate API
neo deps x.com [--min-confidence 1]         # Dipendenze dati risposta→richiesta
neo workflow discover|show|run <name>       # Scoperta e replay di workflow multi-step
neo suggest x.com                           # Analisi delle capacità dell'AI
neo export-skill x.com                      # Genera SKILL.md pronto per agenti

# --- Automazione UI (v2) ---
neo snapshot [-i] [-C] [--json]             # Albero di accessibilità con mapping @ref
neo click @ref [--new-tab]                  # Clicca elemento per @ref
neo fill @ref "text"                        # Pulisci e riempi input
neo type @ref "text"                        # Aggiungi testo all'input
neo press <key>                             # Tasto tastiera (supporta Ctrl+a, Enter, ecc.)
neo hover @ref                              # Passa sopra l'elemento
neo scroll <dir> [px] [--selector css]      # Scorri per direzione
neo select @ref "value"                     # Imposta valore dropdown
neo screenshot [path] [--full] [--annotate] # Cattura screenshot
neo get text @ref | neo get url | neo get title  # Estrai informazioni
neo wait @ref | neo wait --load networkidle | neo wait <ms>  # Aspetta elemento/carico/tempo

# --- Interazione con la pagina ---
neo read github.com                         # Estrai testo leggibile
neo eval "document.title" --tab github.com  # Esegui JS nella pagina
neo open https://example.com                # Apri URL

# --- Mock e Bridge ---
neo mock x.com [--port 8080 --latency 200]  # Server mock dallo schema
neo bridge [--json] [--interactive]         # Flusso di cattura WebSocket in tempo reale

# --- Diagnostica ---
neo doctor                                  # Verifica Chrome, estensione, schemi
neo reload                                  # Ricarica estensione dalla CLI
neo tabs [filter]                           # Elenca schede Chrome aperte

Sessioni e supporto multi-app

Neo non è solo per Chrome. Qualsiasi app con supporto CDP funziona — incluse le app Electron:

# Avvia VS Code con CDP e connettiti
neo launch code --port 9230
neo snapshot                # Vedi l'albero di accessibilità di VS Code
neo click @14               # Clicca una voce di menu

# Oppure connettiti a un'app Electron già in esecuzione
neo connect --electron slack

# Inietta lo script di cattura di Neo in qualsiasi target CDP
neo inject --persist        # Sopravvive alla navigazione della pagina
neo inject --tab slack      # Target specifico

Le sessioni vengono salvate automaticamente. Passa da una all'altra con --session:

neo --session vscode snapshot
neo --session chrome api x.com HomeTimeline

Automazione UI (v2)

Neo v2 aggiunge un livello completo di interazione UI costruito sull'albero di accessibilità — niente screenshot, niente coordinate, niente corrispondenza pixel:

# 1. Fai uno snapshot — ogni elemento interattivo ottiene un @ref
neo snapshot
#  @1  button "Sign in"
#  @2  textbox "Search"
#  @3  link "Pricing"

# 2. Interagisci tramite @ref
neo click @1
neo fill @2 "AI agents"
neo press Enter
neo screenshot results.png --full

Questo dà agli agenti AI un modo veloce e semantico per interagire con qualsiasi UI. Combinalo con la cattura API per un approccio a doppio canale: usa le API quando esistono, ricadi sulla UI quando non ci sono.

Il bridge crea un canale WebSocket persistente tra l'estensione e la CLI. L'estensione si collega automaticamente a ws://127.0.0.1:9234 e trasmette ogni cattura in tempo reale. In modalità interattiva, puoi interrogare direttamente l'estensione: ping, status, capture.count, capture.list, capture.domains, capture.search, capture.clear.

Architettura

┌─────────────────────────────────────┐
│  Chrome / Electron App (CDP)         │
│                                      │
│  inject/interceptor.ts               │
│    ├─ Monkey-patches fetch & XHR     │
│    ├─ Intercepts WebSocket/SSE       │
│    ├─ Tracks DOM triggers (click →   │
│    │   API correlation)              │
│    └─ Records full request/response  │
│                                      │
│  content/index.ts                    │
│    └─ Bridges page ↔ extension       │
│                                      │
│  background/index.ts                 │
│    ├─ Persists to IndexedDB (Dexie)  │
│    ├─ Per-domain cap (500 entries)   │
│    └─ WebSocket Bridge client        │
│                                      │
└──────────────┬──────────────────────┘
               │ Chrome DevTools Protocol
┌──────────────┴──────────────────────┐
│  CLI: neo (Node.js)                  │
│                                      │
│  Layer 1: API Capture & Replay       │
│  ├─ neo capture → traffic management │
│  ├─ neo schema  → API discovery      │
│  ├─ neo exec    → execute in browser │
│  ├─ neo api     → smart schema call  │
│  ├─ neo replay  → re-run captured    │
│  └─ neo flows/deps → pattern analysis│
│                                      │
│  Layer 2: UI Automation (v2)         │
│  ├─ neo snapshot → a11y tree + @refs │
│  ├─ neo click/fill/type/press/hover  │
│  ├─ neo scroll/select/screenshot     │
│  └─ neo get/wait                     │
│                                      │
│  Session Management                  │
│  ├─ neo connect/launch/discover      │
│  ├─ neo tab → target switching       │
│  └─ neo inject → script injection    │
│                                      │
└──────────────┬──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│  AI Agent (OpenClaw / any LLM)       │
│  ├─ API-first: schema → exec/api     │
│  ├─ UI fallback: snapshot → click    │
│  └─ Dual-channel automation          │
└──────────────────────────────────────┘

Demo nel mondo reale

Pubblica un tweet tramite API catturata

# 1. Naviga normalmente su X — Neo cattura le mutazioni GraphQL
neo schema show api.x.com

# 2. Trova l'endpoint CreateTweet
neo capture search "CreateTweet" --method POST

# 3. Riproduci con l'autenticazione originale (cookie ereditati automaticamente)
neo replay abc123 --tab x.com

# 4. Oppure crea una nuova chiamata con header di autenticazione rilevati automaticamente
neo exec "https://x.com/i/api/graphql/.../CreateTweet" \
  --method POST --auto-headers \
  --body '{"variables":{"tweet_text":"Hello from Neo!"},...}'

Capisci cosa fa un pulsante

Il tracciamento dei trigger di Neo mappa le interazioni UI alle chiamate API:

neo schema show github.com
# Output includes:
#   POST /repos/:owner/:repo/star  (3x, 280ms)
#     ← click button.js-social-form "Star" (3x)

Monitoraggio in tempo reale del traffico API

neo capture watch api.openai.com
# 14:23:01  POST 200 /v1/chat/completions (1230ms)
# 14:23:05  SSE_MSG 200 /v1/chat/completions (0ms) [sse]

Archiviazione

Limite per dominio: massimo 500 catture per dominio, le più vecchie vengono eliminate automaticamente
Troncatura del corpo: i corpi delle risposte sono limitati a 100KB
Posizione: IndexedDB di Chrome (database neo-capture-v01)
Schemi: esportabili come file JSON per la persistenza tra dispositivi

Filtraggio intelligente

L'intercettore ignora automaticamente il rumore:

Asset statici (immagini, font, CSS, bundle JS)
Analytics/tracciamento (Google Analytics, Meta Pixel, Sentry, ecc.)
Interne del browser (chrome-extension://, data:, blob:)
Rate limiting: massimo 3 catture per schema URL al minuto (previene il gonfiaggio degli endpoint di polling)

Sicurezza e Privacy

Neo funziona completamente in locale — nessun server esterno, nessuna telemetria, nessun dato esce dal tuo computer.

Cosa cattura Neo: Ogni chiamata fetch/XHR/WebSocket che il tuo browser effettua su ogni sito web. È potente ma invasivo per progettazione.

Offuscamento degli header di autenticazione (v1.1.0+): I valori degli header di autenticazione (Bearer token, CSRF token, cookie, ID di sessione) vengono offuscati al momento della cattura prima dell'archiviazione. IndexedDB memorizza solo i nomi degli header, non i valori. Quando --auto-headers esegue una chiamata API, recupera gli header di autenticazione live dal browser in tempo reale tramite CDP — non riproduce mai le credenziali archiviate.

Cosa dovresti sapere:

Raccomandazioni:

Controlla periodicamente i domini catturati: neo capture domains
Elimina le catture sensibili: neo capture clear banksite.com
Non installare Neo su macchine condivise dove altri hanno accesso locale
La porta CDP (9222) non dovrebbe essere esposta oltre localhost

Neo è uno strumento per sviluppatori che scambia superficie di privacy per capacità. Usalo consapevolmente.

Stack tecnologico

TypeScript, Vite (build multi-entry)
Chrome Manifest V3
Dexie.js (wrapper IndexedDB)
Chrome DevTools Protocol per la comunicazione CLI ↔ browser
Nessun server backend, nessuna dipendenza esterna a runtime

Roadmap

Licenza

MIT

Ambito di cattura	`<all_urls>` — Neo vede il traffico su ogni sito, inclusi banking, email, portali medici
Script di contenuto	Esegue nel mondo `MAIN` (condivide il contesto JS con le pagine) per intercettare fetch/XHR
Porta CDP	La CLI richiede Chrome sulla porta 9222 — qualsiasi processo locale può connettersi a questa porta
Corpi delle risposte	Memorizzati in IndexedDB (troncati a 100KB) — possono contenere dati personali dalle risposte API
File schema	Memorizzano solo la struttura degli endpoint (percorsi, nomi di header, forme delle risposte) — nessuna credenziale o dato utente
Esportazione	`neo capture export` offusca l'autenticazione per impostazione predefinita; `--include-auth` richiede un'esplicita opt-in

Più Popolari

neo

Neo