SeaGOAT Documentation

SeaGOAT uses YAML files for configuration. Settings are merged from two sources:

1. Global configuration files: System-wide settings. Use the command seagoat-server server-info to locate this file on your system.
2. Project configuration files: Project-specific settings located in a file named .seagoat.yml in the root folder of your repository.

Precedence: Project-level configuration values take precedence over global configuration values when they define the same key.

When the SeaGOAT MCP server is connected to an AI assistant (like Claude Desktop), the assistant gains access to the search_code tool. This tool allows the assistant to perform semantic searches against your local codebase via the running SeaGOAT server.

You can trigger this tool by asking natural language questions such as:

• "Search my codebase for the login authentication logic"
• "Find code related to data processing in src/utils"

SeaGOAT uses pytest for automated testing. All commands should be prefixed with poetry run to ensure they execute within the project's virtual environment.

Common Test Commands

• Run all tests: poetry run pytest .
• Watch mode (runs tests automatically on file save): poetry run ptw
• Test only changed files: poetry run pytest . --testmon
• Update snapshots: If using snapshot testing, use poetry run pytest --snapshot-update to refresh snapshots.

# Run all tests
poetry run pytest .

# Watch mode
poetry run ptw

# Test changed files
poetry run pytest . --testmon

# Update snapshots
poetry run pytest --snapshot-update

The seagoat command allows you to perform semantic and pattern-based searches across your codebase. It uses ChromaDB and ripgrep to combine AI-driven vector queries with regular expressions.

Note: SeaGOAT requires a Git repository to function, as it uses Git history to improve result relevance. The CLI communicates with a SeaGOAT server; if the server is not running, you will be prompted to start it using seagoat-server start {repo_path}.

seagoat <query> [repo_path] [OPTIONS]

SeaGOAT uses pre-commit to enforce code style and run automated checks before commits. It is highly recommended to install these hooks so they run automatically during your git workflow.

To install the hooks:

poetry run pre-commit install

If you prefer not to use hooks, you can run all checks manually on all files using:

poetry run pre-commit run --all-files

To boot up the server for a specific repository, use the start command. You can optionally specify a port; otherwise, a random port will be assigned. Even with a random port, the SeaGOAT CLI can automatically locate the server.

seagoat-server start <repo_path> [--port=<custom_port>]

• <repo_path>: Path to your Git repository.
• --port: (Optional) Run the server on a specific port.

To install SeaGOAT, ensure you have the following dependencies installed:

• Python 3.11 or newer
• ripgrep
• bat (optional, but highly recommended for colored output)

If bat is installed, SeaGOAT uses it to display results with color. If bat is missing but color is enabled, SeaGOAT falls back to using pygments for highlighting.

Install SeaGOAT using pipx:

pipx install seagoat

To test your local changes manually, run the project binaries or interactive shells through Poetry to ensure you are using the correct virtual environment.

Manual Execution

• Run the server: poetry run seagoat-server
• Run the CLI tool: poetry run gt (or seagoat)
• Interactive Python: poetry run ipython

SeaGOAT requires a running server to provide fast semantic search results. The server can be run entirely locally and does not require an internet connection.

To start the server for a specific repository:

seagoat-server start /path/to/your/repo

To stop the server for a specific repository:

seagoat-server stop /path/to/your/repo

To develop SeaGOAT, you need to clone the repository, install dependencies using Poetry, and verify the setup with tests.

Prerequisites

• Git
• Python 3.11 or newer
• Poetry

Setup Steps

1. Clone the repository:

   git clone git@github.com:kantord/SeaGOAT.git
   cd SeaGOAT

2. Install dependencies: Use Poetry to manage dependencies and create the virtual environment:

   poetry install

3. Verify installation: Run the test suite to ensure the environment is correct:

   poetry run pytest

SeaGOAT uses pre-commit for linting and automatic code formatting. While these run automatically during commits if hooks are installed, you can trigger them manually for the entire codebase using:

pre-commit run --all-files

(Note: If running via Poetry, use poetry run pre-commit run --all-files)