SeaGOAT: local semantic code search with a server, a vector store and ripgrep

The gap SeaGOAT fills between ripgrep and a chat interface

ripgrep answers questions you already know how to phrase. You type a literal string or a pattern and it returns lines. That breaks down when you remember the intent of a piece of code but not its vocabulary. SeaGOAT targets exactly that gap: the README describes it as a local search tool that uses vector embeddings to search a codebase semantically. The example query in the documentation is `gt "Where are the numbers rounded"`, which is not a string that appears in most source trees. The tool is aimed at developers working on a repository they already have on disk, who want fuzzy, intent-level retrieval without pasting code into a hosted service. The README is explicit that SeaGOAT does not rely on third party or remote APIs and runs everything locally through a server on your own machine.

Two retrieval paths running side by side

The architecture has two distinct matching mechanisms that feed one interface. The first is ChromaDB, a vector database, paired with a local vector embedding engine and telemetry disabled by default, according to the FAQ. The second is ripgrep, the regular-expression search engine, which supplies keyword and pattern matches. This matters because the two paths have different failure modes. Embeddings are good at intent and bad at exactness; ripgrep is the reverse. The README shows both styles: `gt "Where are the numbers rounded"` for the semantic path and `gt "function calc_.* that deals with taxes"` for the regex path. A query can therefore mix a natural-language phrase with a pattern, which is a more useful design than picking one retrieval model and forcing every query through it.

Why there is a server process and what it does to your workflow

SeaGOAT does not index on demand. The README states you must start a server before querying a repository, using `seagoat-server start /path/to/your/repo`, and stop it with `seagoat-server stop /path/to/your/repo`. The FAQ gives the reason plainly: SeaGOAT relies heavily on vector embeddings and vector databases, which at the moment cannot be replaced with an architecture that processes files on the fly. That is a real constraint, not an implementation detail you can configure away. It means one long-running process per repository you want indexed, and a lifecycle to manage. The upside the FAQ claims is speed of response, and it also notes the server can run entirely locally and works without an internet connection. It can also be exposed so other computers connect to it, which is a deliberate choice rather than an accident.

Installation and the commands you actually type

The dependencies listed in the README are Python 3.11 or newer and ripgrep, with bat optional but highly recommended. Installation through pipx is a single command: `pipx install seagoat`. Once the server is running, queries go through either `gt` or `seagoat`, both of which the README presents as equivalent entry points. Output formatting is conditional. When bat is installed and color is enabled, bat renders results. When SeaGOAT is used as part of a pipeline, it falls back to a grep-line output format. When color is enabled but bat is absent, highlighting is done with pygments. If you script against SeaGOAT, the pipeline behavior is the part to design around, because the human-readable rendering and the machine-readable rendering are not the same thing.

Configuration surface and the .seagoat.yml file

Configuration is YAML, either global or per project through a `.seagoat.yml` file. The README gives one concrete key, `server.port`, set to 31134 in the example. The documentation link points to a fuller configuration reference that is not reproduced in the README, so the exact set of tunable keys cannot be confirmed from the repository text alone. What can be confirmed is that the port is project-scoped configuration, which implies you can run more than one SeaGOAT server on a machine as long as the ports differ. That is worth knowing before you start a second repository, since a port collision is the obvious first failure. Everything else about the config file, including whether model selection or file-type overrides are exposed, requires reading the linked docs.

The hard-coded file type list is the sharpest limitation

SeaGOAT is, in the README's own words, hard coded to process a fixed set of formats: text, Markdown, Python, C and headers, C++, TypeScript, JavaScript, HTML, Go, Java, PHP and Ruby. There is no documented include or exclude pattern for other extensions. If your repository is Rust, Kotlin, Swift, Scala, Elixir, shell scripts or Terraform, those files are not part of the semantic index as described. This is the single most consequential constraint in the project, because it is not a performance tuning knob. It determines whether SeaGOAT can see your code at all. A polyglot monorepo will get partial coverage, and the missing portion will be invisible rather than reported as an error.

Indexing is deliberately slow, and results are provisional while it runs

The FAQ addresses a question users will ask immediately: why is SeaGOAT processing files slowly while barely using CPU? The stated answer is that it is an intentional design choice so you can keep using your computer while files are processed, and that this does not affect query performance. Two consequences follow. First, the initial index on a large repository takes time by design, not because something is broken. Second, the README says you can query while processing is still underway, and that in that state you get a warning with an estimation of the accuracy of your results. Regex and full-text results are displayed from the very beginning. That warning is the mechanism you should watch, because it is the only signal distinguishing a complete answer from a partial one.

Platform support and the honest state of the FAQ

The README labels Linux as tested, macOS as partly tested with a link to an issue, and Windows as needing help. That is a candid disclosure rather than a support matrix, and it should be read as such. The FAQ also carries a disclaimer that its points are indications of how SeaGOAT works and not a legal contract, and invites users to read the source or open an issue if they have privacy or safety concerns. On the AI question, the project draws a line: SeaGOAT is a search engine, not a code generator, so it does not create AI-derived work, though a language model is used to produce vector embeddings via ChromaDB's default model. That distinction is defensible, and the README does not overstate it.

How this differs from a plain grep-based index

The obvious alternative for most teams is a keyword index built on ripgrep or a similar tool, driven by a full-text engine such as a Zoekt-style trigram index or a code search service. The difference in approach is the retrieval model, not the language. A keyword index requires you to guess the identifier, the comment wording or the string literal that exists in the file. SeaGOAT relaxes that requirement by embedding files into a vector space and matching on proximity of meaning, while keeping ripgrep in the loop for cases where you do know the pattern. The trade is that you take on a server process, an embedding model, a vector store and a per-repository index that must be built before semantic results are trustworthy. A pure ripgrep workflow has none of that overhead and is instant on a cold checkout. SeaGOAT is the better fit when you repeatedly search for concepts rather than tokens.

Maintenance cost, licence and what to verify before adopting

SeaGOAT is MIT licensed, which is permissive and imposes no copyleft obligation on your own code. That is the extent of what can be said here without giving legal advice; the licence text is the authority. On maintenance, the release history shows frequent patch releases through May 2025, and the repository was last pushed in September 2026, so the project is active rather than dormant. The practical maintenance cost is operational rather than financial: a server process per indexed repository, a `.seagoat.yml` port to keep unique, an initial indexing pass that is slow on purpose, and a supported-extension list you cannot extend through configuration as documented. If your team already runs background services per developer machine, that cost is small. If your workflow assumes a stateless CLI that finishes in milliseconds, it is a different shape of tool.

Editorial conclusion

Adopt SeaGOAT if you work in a Linux environment, your repository is mostly Python, TypeScript, Go, Java, Ruby, PHP, C, C++ or Markdown, and you want natural-language queries without sending code to a remote API. Do not adopt it if you need Windows support, if your codebase is dominated by file types outside the hard-coded list, or if you cannot run a background server per repository. Before committing, verify that `seagoat-server start` completes an initial index on your largest repository, confirm the `.seagoat.yml` port does not collide with anything else on the machine, and check whether the embedding model ChromaDB selects by default is acceptable under your own policy.

Official sources

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