Skip to content

Configuring SeaGOAT

Introduction

Some features of SeaGOAT can be configured through config files. All configuration files are written in the YAML format.

There are two types of configuration files:

  • Global configuration files. Use seagoat-server server-info to find the location of this file on your system. Learn more.
  • Project configuration files. Located in a file called seagoat.yml in the root folder of your repository.

Both of these types of configuration files have the exact same format, and your project-wide configuration files are merged with the global configuration. Whenever both your local as well as global configuration files define a value, the local value takes precedence.

Project configuration files come with the repository, so SeaGOAT does not trust them with settings that decide where your code or credentials are sent or who can reach them. generative, server.host, server.port, client.host and server.chroma.embeddingFunction are only read from the global configuration file; in a project configuration file they are ignored with a warning.

This is an example of a configuration file:

# global config file

server:
  port: 31134  # A port number to run the server on

  # Increase number of commits used for computing frecency score
  # Default is `5000`, set to `null` to read all history
  readMaxCommits: 5000

  # globs to ignore in addition to .gitignore
  ignorePatterns:
    - "**/locales/*" # Ignore all files inside 'locales' directories
    - "**/*.po"     # Ignore all gettext translation files

  # ChromaDB vector search configuration
  chroma:
    embeddingFunction:
      name: "DefaultEmbeddingFunction"
      arguments: {}
    maxVectorDistance: 1.5  # Maximum vector distance for results (0.1-10.0)
    maxChunksToFetch: 100   # Maximum chunks to fetch from vector DB (10-1000)
    nResultsMultiplier: 2   # Multiplier for over-fetching results (1.0-10.0)

  # Ripgrep text search configuration
  ripgrep:
    maxFileSize: 200        # Maximum file size to cache in KB (1KB-10MB)
    maxMmapSize: 500        # Maximum memory-mapped cache size in MB (10-10000 MB)

  # Engine processing configuration
  engine:
    # Deprecated and ignored: accepted for compatibility, but has no effect
    minChunksToAnalyze:
      minValue: 40
      percentage: 0.2
    maxWorkers: 1           # Maximum worker threads (1-32)

  # Query defaults
  query:
    defaultLimitClue: 500   # Default result limit (10-10000)
    defaultContextAbove: 3  # Default context lines above results (0-50)
    defaultContextBelow: 3  # Default context lines below results (0-50)

client:
  # Connect the CLI to a remote server (global configuration file only)
  host: https://example.com/seagoat-instance/

Environment variables

Two environment variables let you override where SeaGOAT stores its caches and its global configuration file, for example in CI, containers or test suites:

  • SEAGOAT_CACHE_DIR: directory for per-repository caches and, under a servers subdirectory, the instance file and repositories.json. Defaults to your platform's user cache directory (e.g. ~/.cache/seagoat on Linux).
  • SEAGOAT_CONFIG_DIR: directory for the global config.yml. Defaults to your platform's user configuration directory (e.g. ~/.config/seagoat on Linux).

They take precedence over the platform defaults and work on every operating system (unlike the XDG_CACHE_HOME / XDG_CONFIG_HOME variables, which platformdirs ignores on macOS and Windows).

Available configuration options

Server

Server-related configuration resides under the server attribute in your config files.

The following values can be configured:

  • host (global configuration file only): The network interface the server listens on. Defaults to 127.0.0.1, so only your own computer can reach the server. Set it to 0.0.0.0 to accept connections from other computers, for example when hosting the server remotely. SeaGOAT has no authentication, so anyone who can reach the server can list and search every repository the instance serves.
  • port (global configuration file only): The port number the SeaGOAT instance will run on. The --port option of seagoat-server start overrides it when the command starts the instance. A repository's .seagoat.yml cannot change it; if it tries, SeaGOAT warns and ignores it.
  • There is no repositories option. The repositories an instance serves are listed in the repositories.json file next to the instance file in SeaGOAT's cache directory (for example ~/.cache/seagoat-servers/repositories.json on Linux), and seagoat-server start <repo_path> writes it. Removing a repository from the list takes effect when the instance restarts.
  • ignorePatterns: A list of glob patterns to ignore. Keep in mind that all files ignored by .gitignore are already ignored. You probably should not need to configure this value. It is only useful if there are some files that you wish to keep in git, but you wish to hide from SeaGOAT. Learn more about globs
  • chroma: Configurations for the ChromaDB based features. Has the following attributes:
  • embeddingFunction (global configuration file only):
    • name: Name of the embedding function to use. See ChromaDB's docs for more If the name contains a :, it is treated as module.path:ClassName and imported with Python's importlib, so any installed embedding function class can be used.
    • arguments: Arguments to pass to the embedding function.
  • maxVectorDistance: Maximum vector distance for results (default: 1.5, range: 0.1-10.0)
  • maxChunksToFetch: Maximum chunks to fetch from vector database (default: 100, range: 10-1000)
  • nResultsMultiplier: Multiplier for over-fetching results (default: 2, range: 1.0-10.0)

If you wanted to use the ONNXMiniLM_L6_V2 embedding model with TensorRT:

server:
  chroma:
    embeddingFunction:
      name: "ONNXMiniLM_L6_V2"
      arguments:
        preferred_providers: ["TensorrtExecutionProvider"]
    maxVectorDistance: 1.2
    maxChunksToFetch: 150
    nResultsMultiplier: 2.5
  • ripgrep: Configurations for the ripgrep text search engine. Has the following attributes:
  • maxFileSize: Maximum file size to cache in KB (default: 200, range: 1-10240 KB)

  • maxMmapSize: Maximum memory-mapped cache size in MB (default: 500, range: 10-10000 MB)

  • engine: Configurations for the search engine processing. Has the following attributes:

  • minChunksToAnalyze (deprecated, ignored): This setting no longer has any effect. It is still accepted for compatibility so existing configuration files keep validating, but SeaGOAT logs a warning and ignores it. This applies to configuration files. The explicit library argument Engine.analyze_codebase(minimum_chunks_to_analyze=...) remains supported. Its synchronous wrapper retains the historical default quota; the server queues every pending chunk in batches.

  • maxWorkers: Maximum worker threads for parallel processing (default: 1, range: 1-32)

  • query: Default values for query parameters. Has the following attributes:

  • defaultLimitClue: Default result limit (default: 500, range: 10-10000)
  • defaultContextAbove: Default context lines above results (default: 3, range: 0-50)
  • defaultContextBelow: Default context lines below results (default: 3, range: 0-50)

Client

Configuration for the CLI (gt command) resides under the client attribute.

The following values can be configured:

  • host (global configuration file only): The URL of the SeaGOAT instance to connect to. This is only needed when you are hosting your SeaGOAT server on a remote computer. With client.host set, the CLI sends no repository path, so that remote instance must serve exactly one repository.

Performance Tuning

For Large Repositories

For repositories with many files or large codebases, consider these optimizations:

server:
  # Increase file size limit to include larger files
  ripgrep:
    maxFileSize: 1024     # 1MB instead of 200KB
    maxMmapSize: 2000     # 2GB instead of 500MB

  # Increase processing capacity
  engine:
    maxWorkers: 4         # Use more CPU cores

  # Optimize vector search
  chroma:
    maxChunksToFetch: 200 # Fetch more results for better recall
    nResultsMultiplier: 3 # Over-fetch more aggressively

For Better Search Quality

To improve search result quality at the cost of some performance:

server:
  chroma:
    maxVectorDistance: 2.0    # Accept more distant matches
    maxChunksToFetch: 300     # Fetch more candidates
    nResultsMultiplier: 4     # Over-fetch more results

  query:
    defaultLimitClue: 1000    # Return more results by default
    defaultContextAbove: 5    # More context lines
    defaultContextBelow: 5

For Memory-Constrained Systems

To reduce memory usage:

server:
  ripgrep:
    maxFileSize: 100      # 100KB instead of 200KB
    maxMmapSize: 200      # 200MB instead of 500MB

  engine:
    maxWorkers: 1         # Single-threaded processing

  chroma:
    maxChunksToFetch: 50  # Fetch fewer results
    nResultsMultiplier: 1.5