SeaGOAT : recherche sémantique locale dans une base de code, sans envoi de données

Le problème visé : retrouver du code par son intention, pas par son texte

grep et ripgrep excellent quand on connaît le motif exact. Dès qu'on cherche une intention (« où les nombres sont arrondis »), il faut deviner les identifiants, les noms de fonctions et les conventions de l'auteur du dépôt. SeaGOAT part de ce constat et propose une requête en langage naturel, tout en conservant la recherche par expression régulière. Le README donne les deux formes côte à côte : gt "Where are the numbers rounded" et gt "function calc_.* that deals with taxes". L'outil s'adresse donc à un développeur qui explore une base qu'il connaît mal, ou qui revient sur du code écrit plusieurs mois plus tôt. La cible est individuelle : un dépôt, une machine, un serveur lancé à la demande. Rien dans le matériel fourni ne décrit un usage en équipe, un partage d'index entre plusieurs postes ou une intégration dans une forge logicielle.

Deux moteurs derrière une seule commande

L'architecture repose sur deux composants distincts. Le premier est ChromaDB, une base de données vectorielle accompagnée d'un moteur d'embeddings local. Le second est ripgrep, utilisé pour les correspondances par expression régulière et par mot-clé. Le README indique explicitement que ripgrep sert à fournir ces correspondances « en plus » des résultats sémantiques. La commande gt interroge les deux et fusionne les réponses. Cette combinaison explique un comportement utile : les résultats issus de ripgrep apparaissent immédiatement, même lorsque l'indexation vectorielle n'est pas terminée. SeaGOAT utilise le modèle d'embeddings par défaut de ChromaDB, et la télémétrie est désactivée par défaut d'après le README. Aucun appel à une API distante n'est décrit dans le fonctionnement nominal.

Pourquoi un serveur, et ce que cela implique

SeaGOAT ne traite pas les fichiers à la volée. Le README justifie le serveur par la latence : les embeddings et la base vectorielle ne peuvent pas, en l'état, être remplacés par une architecture qui lit les fichiers au moment de la requête. Il faut donc lancer seagoat-server start /path/to/your/repo avant toute recherche, puis seagoat-server stop /path/to/your/repo pour l'arrêter. Le serveur écoute sur un port, configurable dans .seagoat.yml via la clé server.port, avec 31134 comme valeur d'exemple. Ce choix a une conséquence pratique : la recherche dépend d'un processus qui tourne en arrière-plan. Le README mentionne aussi la possibilité d'exposer un serveur pour que d'autres machines s'y connectent, mais sans documenter de mécanisme d'authentification ou de contrôle d'accès. À traiter comme une fonctionnalité à vérifier dans le code source avant tout usage en réseau.

Installation et configuration : les commandes réelles

Les prérequis sont Python 3.11 ou plus récent, ripgrep, et bat en option mais recommandé. L'installation se fait avec pipx install seagoat. bat sert à coloriser les résultats ; sans lui, SeaGOAT retombe sur pygments lorsque la couleur est activée, et sur un format de sortie type grep lorsque l'outil est utilisé dans un pipeline. La configuration passe par des fichiers YAML, globaux ou par projet via .seagoat.yml. Le README ne donne qu'un seul exemple de clé, server.port, et renvoie à la documentation en ligne pour le reste. C'est une limite du matériel disponible : impossible de lister ici les autres options de configuration sans les inventer. Pour le développement, le dépôt utilise Poetry : poetry install, puis poetry run pytest ., avec poetry run ptw pour le mode watch et poetry run pytest . --testmon pour ne tester que les fichiers modifiés.

Une liste de formats codée en dur

SeaGOAT ne traite que les extensions énumérées dans le README : .txt, .md, .py, .c, .h, .cpp, .cc, .cxx, .hpp, .ts, .tsx, .js, .jsx, .html, .go, .java, .php et .rb. Le README précise que cette liste est actuellement figée dans le code. Un projet en Rust, en Kotlin, en Swift, en C# ou en YAML sera donc partiellement invisible : les fichiers de configuration, les schémas et les manifestes ne remonteront pas dans les résultats sémantiques. C'est le point de friction le plus concret pour un adoptant. La parade consiste à ajouter une extension .txt, ce qui dénature le dépôt. L'encodage préféré est UTF-8, les autres encodages devraient fonctionner dans la plupart des cas, et les fichiers binaires sont ignorés. Un dépôt contenant beaucoup de ressources binaires ou de formats non listés verra sa couverture se réduire sans avertissement explicite au moment de la requête.

Le coût d'indexation assumé

Le README reconnaît que le traitement des fichiers peut être long sur un gros dépôt, et présente cela comme un choix délibéré : SeaGOAT est conçu pour ne pas saturer la machine pendant l'indexation. La consommation CPU reste faible, ce qui explique la lenteur apparente. Deux conséquences en découlent. D'abord, la première indexation d'un dépôt volumineux prend du temps, et le README ne donne aucune estimation chiffrée, donc aucune ne peut être avancée ici. Ensuite, les requêtes restent utilisables pendant l'indexation : SeaGOAT affiche un avertissement avec une estimation de la précision des résultats, et les correspondances ripgrep sont disponibles dès le départ. Le compromis est explicite : on accepte une indexation lente pour garder une machine réactive. Sur un serveur d'intégration continue ou une machine dédiée, ce compromis n'a plus de sens, et un outil qui indexe plus agressivement serait plus adapté.

Alternatives et différences d'approche

ripgrep seul reste l'alternative la plus directe, et elle n'est pas concurrente : SeaGOAT l'utilise en interne. La différence tient à l'absence d'index persistant et à l'absence de recherche par intention. Un autre axe de comparaison est l'usage d'un assistant hébergé, qui indexe le dépôt chez un fournisseur et répond en langage naturel. SeaGOAT prend le chemin inverse : tout s'exécute localement, sans API tierce, au prix d'un serveur à maintenir et d'une liste de formats restreinte. Le README signale d'ailleurs que de futures fonctionnalités optionnelles pourraient envoyer des données à distance si elles apportent un gain, ce qui n'est pas le cas dans la version décrite. Enfin, le même auteur développe zeitgrep, présenté dans le README comme un autre outil de recherche en cours de développement. Le matériel fourni ne détaille ni son fonctionnement ni ses différences avec SeaGOAT, donc la comparaison s'arrête là.

Licence, maintenance et ce qu'il reste à vérifier

SeaGOAT est publié sous licence MIT, ce qui autorise la réutilisation, la modification et la redistribution avec conservation de la mention de copyright. Aucune clause de brevet explicite n'est mentionnée dans le matériel fourni. Le rythme de publication est élevé : trois versions en mai 2025, dont v0.54.15, v0.54.16 et v0.54.17, et un dernier push en septembre 2026. Un numéro de version en 0.54 signale une API et un comportement encore mouvants, donc des mises à jour fréquentes à prévoir. Le support des systèmes est inégal et documenté comme tel : Linux est indiqué comme testé, macOS comme partiellement testé, Windows comme nécessitant de l'aide. Ces mentions renvoient à des tickets ouverts dans le dépôt, ce qui indique que le support n'est pas acquis. Le README précise aussi que la FAQ n'est pas un contrat légal et invite à examiner le code source en cas de doute sur la confidentialité. C'est la démarche à suivre avant tout déploiement sur un dépôt sensible.

Conclusion éditoriale

SeaGOAT s'adresse aux développeurs qui travaillent sur un dépôt local et veulent interroger le code en langage naturel sans transmettre leurs sources à un service tiers. Ceux qui cherchent un index de dépôts distants, qui ont besoin d'indexer des extensions hors de la liste codée en dur (Rust, Kotlin, Swift, YAML), ou qui veulent un service partagé par une équipe entière, doivent d'abord vérifier le contenu de cette liste avant d'installer quoi que ce soit. Le point à contrôler en premier reste l'indexation d'un dépôt réel : lancer seagoat-server start sur une copie du projet et observer quels fichiers sont effectivement traités.

Sources officielles

1. kantord/SeaGOAT on GitHub
2. License: MIT
3. Project website
4. README
5. Releases