How kantord/seagoat works
Project type and purpose
• SeaGOAT is a full-stack, local code search engine CLI application written in Python.
• It consists of two main “faces”:
• A CLI client (seagoat, gt) for querying/searching
• A persistent server (seagoat-server) that indexes files and serves queries
• It leverages ripgrep for text/regex search and ChromaDB as a local vector database for semantic search.
File structure
• Top level:
• seagoat/: core Python package
• seagoat/cli.py: CLI entrypoint
• seagoat/server.py: HTTP server entrypoint
• seagoat/engine.py, cache.py, queue/, repository.py, gitfile.py, result.py: business logic
• seagoat/sources/: adapters for different data sources (Chroma, ripgrep)
• seagoat/utils/: helpers (config, file reading, JSON, display, etc.)
• locustfile.py: performance testing
• docs/, mkdocs.yml: documentation site
• GitHub workflows, CI/CD configs, tests, typing stubs
• Patterns:
• CLI ↔ HTTP server ↔ engine
• Engine enqueues tasks, processes file streams, stores embeddings in a vector DB
• “Sources” abstraction: each query/indexing source implements a common interface
• Background queue (seagoat/queue) decouples indexing from request handling
README for additional insights
• Architecture described implicitly in “How does SeaGOAT work?” and “Why does it need a server?”
• Key external dependencies: Python 3.11, ripgrep, optional bat, ChromaDB (embedded), local file system, Git repo.
Final advice
• Be granular: break “Engine” into subcomponents (Index Worker, Query Handler).
• Both indexing and query-time flows.
• Config layer feeding into Server & Engine.