|
| 1 | +# Agents |
| 2 | + |
| 3 | +## Cursor Cloud specific instructions |
| 4 | + |
| 5 | +### Overview |
| 6 | + |
| 7 | +Sourcebot is a self-hosted code intelligence platform (code search, navigation, AI Q&A). It's a Yarn 4 monorepo with packages under `packages/` and a vendored Go-based search engine (Zoekt) under `vendor/zoekt`. |
| 8 | + |
| 9 | +### Prerequisites |
| 10 | + |
| 11 | +- **Node.js 24+** (required by the project) |
| 12 | +- **Go** (for building Zoekt binaries from `vendor/zoekt`) |
| 13 | +- **Docker** (for PostgreSQL 16 and Redis 7 via `docker-compose-dev.yml`) |
| 14 | +- **universal-ctags** (used by Zoekt for symbol indexing; pre-installed as `ctags`) |
| 15 | + |
| 16 | +### Services and Ports |
| 17 | + |
| 18 | +| Service | Port | Notes | |
| 19 | +|---------|------|-------| |
| 20 | +| Web (Next.js) | 3000 | Redirects to `/onboard` on first run | |
| 21 | +| Backend worker | 3060 | Express + BullMQ job processor | |
| 22 | +| Zoekt WebServer | 6070 | Code search engine (Go binary) | |
| 23 | +| PostgreSQL | 5432 | Via `docker-compose-dev.yml` | |
| 24 | +| Redis | 6379 | Via `docker-compose-dev.yml` | |
| 25 | + |
| 26 | +### Key Commands |
| 27 | + |
| 28 | +Standard dev commands are documented in `CONTRIBUTING.md` and `package.json`. Key ones: |
| 29 | + |
| 30 | +- **Start all services:** `yarn dev` (runs zoekt, backend, web, mcp watcher, schemas watcher concurrently) |
| 31 | +- **Lint:** `yarn workspace @sourcebot/web lint` |
| 32 | +- **Test:** `yarn test` (runs all workspace tests) |
| 33 | +- **Build deps only:** `yarn build:deps` (builds shared packages: schemas, db, shared, query-language) |
| 34 | +- **DB migrations:** `yarn dev:prisma:migrate:dev` |
| 35 | + |
| 36 | +### Non-obvious Caveats |
| 37 | + |
| 38 | +- **Docker must be running** before `yarn dev`. Start it with `docker compose -f docker-compose-dev.yml up -d`. The backend will fail to connect to Redis/PostgreSQL otherwise. |
| 39 | +- **Zoekt binaries** must be built before `yarn dev`. They live in `./bin/` and are built with `go build -C vendor/zoekt -o $(pwd)/bin ./cmd/...`. The `make zoekt` target does this. |
| 40 | +- **Git submodules** must be initialized (`git submodule update --init --recursive`) before building Zoekt. |
| 41 | +- **ctags compatibility:** The installed `ctags` may not support `--_interactive=default` (universal-ctags feature). Zoekt logs a warning but continues to index without symbol data. This does not block functionality. |
| 42 | +- **First run onboarding:** On a fresh database, the web app redirects to `/onboard` where you create an owner account. Credentials login is enabled by default (`AUTH_CREDENTIALS_LOGIN_ENABLED` defaults to `true`). |
| 43 | +- **Config file:** Create a `config.json` at the repo root (referenced by `CONFIG_PATH` in `.env.development`) to configure which repos to index. A minimal example is in `CONTRIBUTING.md`. |
| 44 | +- **Environment variables:** `.env.development` has sensible defaults for local dev. Create `.env.development.local` for overrides (it's gitignored). |
| 45 | +- The backend worker does not expose a health-check endpoint. Verify it's running by checking its logs or that BullMQ jobs are processing. |
| 46 | + |
| 47 | +### Pull Request Workflow |
| 48 | + |
| 49 | +- **CHANGELOG entry required:** Every PR must include a follow-up commit adding an entry to `CHANGELOG.md` under `[Unreleased]`. The entry must be a single sentence describing the change, followed by a link to the PR in the format `[#<id>](https://github.com/sourcebot-dev/sourcebot/pull/<id>)`. Place new entries at the bottom of the appropriate section (`Added`, `Changed`, `Fixed`, etc.). See `CLAUDE.md` and existing entries in `CHANGELOG.md` for the exact conventions. |
0 commit comments