🐦‍⬛ XCrowler

XCrowler est un userscript OSINT qui collecte les tweets visibles sur la timeline d'un compte X (Twitter), directement depuis ton navigateur, avec un rythme de défilement humain pour éviter de te faire bloquer par le rate-limit de la plateforme.

Pourquoi

X/Twitter est une SPA à défilement virtualisé : les tweets hors écran sont retirés du DOM au fur et à mesure du scroll. Pour archiver ou analyser la timeline d'un compte (enquête OSINT, veille, analyse de discours, archivage avant suppression), il faut donc extraire les données au fil du scroll, pas seulement à la fin — et gérer le mur de rate-limit que X impose passé un certain volume de lecture.

XCrowler automatise ce travail : il scrolle à ta place avec un rythme aléatoire (pas de scroll fixe et détectable), détecte l'apparition du mur de rate-limit, met en pause avec un backoff progressif, puis reprend automatiquement — le tout en sauvegardant ta progression pour ne jamais repartir de zéro.

Fonctionnalités

• Extraction en continu pendant le scroll : ID du tweet, auteur (handle + nom complet), date ISO, contenu texte, statistiques brutes (aria-label), médias (images/vidéos), statut retweet, lien direct.
• Pacing humain : délais aléatoires entre chaque pas de scroll, avec une pause longue périodique pour rester discret.
• Détection du mur de rate-limit : scan du texte affiché pour repérer l'écran de blocage de X (FR/EN), avec backoff exponentiel (15 min → jusqu'à 60 min) avant reprise automatique.
• Reprise automatique après rechargement : si le mode auto était actif, la collecte reprend toute seule après une pause de backoff ou un rechargement de page — rien n'est perdu.
• Arrêt automatique intelligent : le script s'arrête de lui-même quand plus aucun nouveau tweet n'apparaît après plusieurs tentatives de scroll.
• Autosauvegarde : export JSON automatique tous les 300 tweets collectés, en plus du stockage persistant local.
• Filtrage : par mot-clé (contenu ou auteur) et par type (avec média / retweets / originaux uniquement).
• Export JSON : téléchargement de la collecte complète ou filtrée, horodaté, par compte.
• Multi-comptes : chaque compte visité a sa propre collecte, stockée séparément.
• 100% local : les données restent dans le stockage du navigateur (GM_setValue/GM_getValue) jusqu'à export. Rien n'est envoyé à un serveur tiers.

Installation

XCrowler est un script utilisateur (userscript). Il te faut d'abord une extension de gestion de scripts, puis installer le script lui-même.

1. Installer un gestionnaire de userscripts

• Tampermonkey (Chrome, Firefox, Edge, Safari, Brave)
• Violentmonkey (Chrome, Firefox, Edge)

2. Installer le script XCrowler

1. Ouvre le gestionnaire de scripts et choisis "Créer un nouveau script".
2. Copie tout le contenu du fichier xcrowler.user.js de ce dépôt.
3. Colle-le dans l'éditeur, en remplaçant le contenu par défaut.
4. Sauvegarde (Ctrl+S).

Alternative : la plupart des gestionnaires détectent automatiquement un fichier .user.js et proposent son installation directement si tu ouvres son URL brute (raw) sur GitHub.

3. Utiliser le script

1. Connecte-toi normalement sur x.com avec ton compte.
2. Va sur la page profil du compte dont tu veux collecter la timeline (x.com/nom_du_compte).
3. Un panneau XCrowler apparaît en bas à droite de l'écran.
4. Clique sur "Démarrer" — le script scrolle et collecte automatiquement, à un rythme volontairement lent pour éviter le rate-limit.
5. Le statut affiche en direct le nombre de tweets collectés.
6. Clique sur "Stopper" à tout moment pour arrêter proprement (les données déjà collectées sont conservées).
7. Utilise le champ de recherche et le menu déroulant pour filtrer la collecte (mot-clé, médias, retweets, originaux).
8. Clique sur "Télécharger tout" ou "Télécharger filtré" pour exporter en JSON.
9. "Réinitialiser" efface la collecte du compte actuellement affiché (avec confirmation).

Si X affiche son mur de rate-limit pendant la collecte, XCrowler le détecte, met le script en pause automatiquement (jusqu'à 60 min avec backoff progressif) puis relance la collecte tout seul — inutile de surveiller en continu.

Format d'export

Chaque tweet exporté a cette structure :

{
  "tweet_id": "1234567890123456789",
  "username": "exemple",
  "fullname": "Nom Complet",
  "date_iso": "2026-01-15T10:23:00.000Z",
  "content": "Texte du tweet...",
  "stats_raw": "12 replies, 34 reposts, 56 likes",
  "media_urls": ["https://pbs.twimg.com/media/..."],
  "is_retweet": false,
  "social_context": "",
  "x_url": "https://x.com/exemple/status/1234567890123456789",
  "collected_at": "2026-01-15T10:24:03.512Z"
}

Structure du dépôt

Fichier	Description
xcrowler.user.js	Le userscript principal, à installer dans Tampermonkey/Violentmonkey
Xcrowler.png	Illustration du projet

Usage responsable

XCrowler ne collecte que des tweets déjà publiquement visibles dans ton propre navigateur, sans contourner d'authentification ni accéder à des données privées — il automatise simplement ce que tu pourrais faire manuellement en scrollant et copiant/collant. Le rythme volontairement lent vise à limiter la charge sur les serveurs de X et à respecter les limites de la plateforme, pas à s'en affranchir.

L'usage de ce script reste soumis aux conditions d'utilisation de X : utilise-le dans un cadre légitime (enquête OSINT, recherche, veille, archivage), à titre personnel, et à tes propres risques.

Licence

MIT