Contribute to Garage

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

rickmark/garage-rag on GitHub ↗ Issues ↗

Ways to help

🐛

Report what you find

A clear bug report is a contribution. In the Mac 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 growing beyond the Mac. 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.

Find your way around

Folder	What’s in it
`garage_python/`	The `garage_rag` Python package: ingestion, extractors, attribution, embeddings, hybrid search, the MCP server and the `garage` CLI. Runs on macOS, Linux and Windows.
`macapp/`	The Swift/SwiftUI Mac 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 Mac app and the Python service.
`ext/`	From-source builds of PostgreSQL, pgvector, Python, llama.cpp, Tesseract and the rest.
`docs/`	This website.

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 Python work

Most changes touch only the Python package, and that needs no Bazel, Xcode or Mac:

git clone https://github.com/rickmark/garage-rag.git
cd garage-rag/garage_python
uv sync                                         # macOS
# uv venv --python 3.14 .venv && uv pip install -e '.[dev]'   # Linux and Windows
.venv/bin/pytest                                # the unit tests mock the database

The tests that need real SQL (tests/test_postgres.py) 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. Each run creates and drops its own throwaway database. Don’t point it at the Mac app’s own database, which holds your real corpus.

Before you push, run the formatter and linters:

.venv/bin/ruff format && .venv/bin/ruff check

Build everything

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

aspect build //...          # everything
aspect build //:macapp      # the Mac app, with its own PostgreSQL, Python and llama.cpp
aspect test //...           # every test
aspect gazelle              # regenerate BUILD files after adding Python sources

The Mac app needs a Mac with Xcode. Windows builds PostgreSQL and Python with each project’s own MSVC build, in .github/workflows/windows.yaml, which is the place to start for Windows work.

Ground rules

Privacy is load-bearing. Only net/egress.py opens outbound connections. No cloud AI SDKs. Communications such as Messages and Mail never go to a server that is not on this computer. The tests in test_egress_block.py check each rule on its own, and a change that weakens one won’t be merged. See privacy internals.
Keep licenses permissive. For example, PDF extraction uses pypdf and pdfplumber because PyMuPDF is AGPL. After changing dependencies, regenerate the third-party notices (python3 tools/third_party_notices.py).
Tests come with the change. Deprecation warnings fail the suite, so fix them rather than silencing them.
Settings are documented. A new or renamed config setting needs its description, and the JSON Schema regenerated (garage config schema --publish).

Send a pull request

Fork the repository and make a branch.
Make your change, with tests, and run them.
Open a pull request against main that says what changed and why. CI runs the Python suite on Linux (with PostgreSQL), format and lint checks, a Swift syntax check and, for build changes, the full macOS and Windows builds.
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.