A Love Wins Media product

Contribute to Garage

Garage is free and open source under the MIT license. The macOS app, the Rust pipeline, the Windows app and this website all live in one repository on GitHub, and contributions of every size are welcome.

Ways to help

🐛

Report what you find

A clear bug report is a contribution. In the macOS app, Report a Bug (in Logs, or the Help menu) assembles the details for you. Elsewhere, the contact page lists what to include.

🪟

Test on Windows and Linux

Garage is cross-platform, and growing. Try the Windows alpha or the Linux command line and tell us what breaks: your distribution, your file types, your MCP client.

📝

Improve the docs

This site is in docs/ in the repository, plain Markdown built by Jekyll. Fixing a confusing step or a typo is a fine first pull request.

🧩

Write code

New extractors, attribution rules, MCP tools, model support, performance and Windows work. Issues are a good place to start: say what you plan before a big change, so it fits. The engineering plans show what is already proposed or under way.

Find your way around

Folder What’s in it
rust/ The pipeline, a Cargo workspace: GarageService (the backend over PostgreSQL), ingestion and the readers, attribution, the embed worker, hybrid search, the MCP server and the garage CLI. Runs on macOS, Linux and Windows.
macapp/ The Swift/SwiftUI macOS app, its XPC services and the garage / garage-mcp launchers.
data/sql/ The database schema, the source of truth. Migrations are idempotent and re-applied, not tracked.
proto/ The gRPC contract between the apps and GarageService.
winapp/ The Windows app (.NET 10, WinUI 3) and its installers.
ext/ From-source builds of PostgreSQL, pgvector, llama.cpp, Tesseract and the rest.
docs/ This website.
docs/plans/ Engineering plans and design notes, published as the plans page.

The architecture guide walks through the pipeline, and the repository’s CLAUDE.md is the detailed map for anyone, human or coding agent, working in the code.

Set up for Rust work

Most changes touch only the Rust workspace, and that needs no Bazel, Xcode or macOS: a Rust toolchain from rustup (it reads rust/rust-toolchain.toml), protoc, and the libgit2, SQLite and, off macOS, Tesseract development packages (brew install libgit2 protobuf on macOS; apt install protobuf-compiler libgit2-dev libsqlite3-dev libtesseract-dev tesseract-ocr-eng pkg-config on Debian and Ubuntu).

git clone https://github.com/rickmark/garage-rag.git
cd garage-rag/rust
cargo test --workspace --features garage-plugin/grpc     # most tests need no database

The tests that need real SQL (garage-service/tests, garage-cli/tests) run when GARAGE_TEST_DATABASE_URL names a PostgreSQL server with pgvector and a superuser role, such as Homebrew’s postgresql@18 or the pgvector/pgvector:pg18 Docker image, and pass without running otherwise. Each run creates and drops its own throwaway database. Don’t point it at the macOS app’s own database, which holds your real corpus.

Before you push, run the formatter and linters:

cargo fmt --check && cargo clippy --workspace --all-targets --features garage-plugin/grpc -- -D warnings

Build everything

The whole repository, the macOS app included, builds with Bazel through the Aspect CLI:

aspect build //...          # everything
aspect build //:macapp      # the macOS app, with its own PostgreSQL and llama.cpp and the Rust libraries linked in
aspect test //...           # every test
aspect gazelle              # regenerate BUILD files after editing proto/

The macOS app needs macOS with Xcode. Windows builds PostgreSQL with its own MSVC build and the Rust libraries with Cargo, in .github/workflows/windows.yaml, which is the place to start for Windows work.

Ground rules

Send a pull request

  1. Fork the repository and make a branch.
  2. Make your change, with tests, and run them.
  3. Open a pull request against main that says what changed and why. CI runs the Rust suite on Linux (with PostgreSQL), format and lint checks, a Swift syntax check and, for build changes, the full macOS and Windows builds.
  4. Be ready for a round of review. Small, focused pull requests get merged fastest.

By contributing, you agree that your contribution is licensed under the project’s MIT license.

💬 Questions?

Not sure where to start, or whether an idea fits? Open an issue and ask. Garage is maintained by Rick Mark-Penwell, and you can support the work on Patreon.