Contributing

grepai works issue first. How to report a bug, request a feature, test a fix or list your tool, and how to build grepai from source.

grepai works issue first: every contribution starts as an issue, and the project does not accept pull requests. The same rules are in the repository’s CONTRIBUTING.md.

Why Issue First

With AI coding tools, writing a fix is rarely the hard part. The hard part is knowing exactly what is wrong, on which setup, and what the right behavior is. A precise issue carries all of that. Reviewing an outside pull request, checking it does not break other setups, and reworking it to fit the rest of the code usually takes longer than implementing the fix from a good issue.

So the most useful thing you can send is a detailed issue. The maintainer implements it, tests it against the current release on real projects, and credits you in the changelog. Pull requests opened anyway are closed with a link to open an issue instead.

Open an Issue

You have	Where	Include
A bug	Bug report form	`grepai version`, OS, embedder and store from `.grepai/config.yaml` (no keys), exact commands, expected vs actual result, logs
A feature idea	Feature request form	The problem you hit and your real use case, then the solution you have in mind
A question	Discussions	What you tried
A security issue	SECURITY.md	Not a public issue

Search the existing issues first. If yours is there, add your setup and logs to it: a second reproduction is often what unblocks a fix.

Other Ways to Help

Test a fix. When a fix lands on a branch, building it and confirming it works on your project is very valuable (see below).
Improve the docs. If a page is wrong, unclear or out of date, open an issue that quotes the passage and says what is wrong.
List your tool. Built something around grepai? See Community Tools.
Talk about it. A star, a post or a talk helps other people find grepai.

Building From Source

You need:

Go 1.25.5 or later (the go directive in go.mod)
Git
Docker, for make lint (it runs golangci-lint in a container)

git clone https://github.com/yoanbernabeu/grepai.git
cd grepai
make build        # builds bin/grepai
make test         # tests with the race detector

To try a branch that contains a fix:

git fetch origin <branch>
git checkout <branch>
make build
./bin/grepai version

Development Commands

Command	What it does
`make build`	Build `bin/grepai`
`make install`	Install `grepai` with `go install`
`make run`	Build, then run `bin/grepai`
`make test`	Run all tests with the race detector (`go test -v -race ./...`)
`make test-cover`	Run tests and write `coverage.out` and `coverage.html`
`make fmt`	Format all Go files with `gofmt -w .`
`make lint`	Run golangci-lint v2.13.2 in Docker
`make lint-local`	Run your locally installed `golangci-lint`
`make pre-commit`	Format, vet, lint and test (see below)
`make build-all`	Cross-compile for Linux, macOS and Windows into `bin/`
`make docs-generate`	Regenerate the CLI reference pages in `docs/src/content/docs/commands/`
`make docs-dev`	Regenerate the CLI pages, then start the docs dev server
`make clean`	Remove `bin/` and coverage files

The default build has no AST chunking or tree-sitter extraction. To build with them, add the treesitter build tag (this needs CGO and a C compiler):

go build -tags treesitter -o bin/grepai ./cmd/grepai

Project Structure

grepai/
├── cmd/
│   ├── grepai/       # CLI entry point
│   └── gendocs/      # Generates the CLI reference pages
├── cli/              # Cobra commands (init, watch, index, search, trace, refs, rpg, mcp-serve, ...)
├── config/           # Project and workspace configuration
├── daemon/           # Background watch daemon
├── embedder/         # Embedding providers and factory.go
├── framework/        # Framework processors (Vue, Svelte, Astro, Solid)
├── git/              # Git and worktree detection
├── indexer/          # Scanner, chunker and indexing orchestration
├── mcp/              # MCP server and tools
├── rpg/              # Repository Planning Graph
├── search/           # Search, hybrid search, boosting
├── stats/            # Token savings stats
├── store/            # Vector stores (GOB, PostgreSQL, Qdrant)
├── trace/            # Symbol extraction and call graphs
├── updater/          # Self-update
├── watcher/          # File watching
└── docs/             # Documentation site (Astro)