Submit a pull request
How to fork OpenQuok, run the monorepo locally, and open a code pull request on GitHub.
Connect your agent today
Draft from chat, review in your calendar, and publish only what you approve.
Improve OpenQuok’s codebase by opening a pull request.
No special permissions are required — fork the repo, make your changes, run the relevant checks, and submit a PR for review.
Repository
Application code lives in the openquok-monorepo monorepo on GitHub. Key packages include backend/, web/, orchestrator/, agent/, sdk/, and common/. See Project architecture for layout and responsibilities.
Workflow
Fork and clone
On GitHub, fork Ratimon/openquok-monorepo, then clone your fork locally:
git clone https://github.com/<your-username>/openquok-monorepo.git
cd openquok-monorepo
corepack enable
pnpm installReplace <your-username> with your GitHub username. For first-time setup (Node version, env files, local Supabase), follow Quick start.
Create a branch
Use a short, descriptive branch name (for example feat/threads-analytics, fix/oauth-callback, or chore/bump-deps):
git checkout -b feat/your-topicMake your changes
Work in the package that matches your change:
| Area | Typical paths |
|---|---|
| API, integrations, migrations | backend/ |
| Dashboard, marketing site, docs app | web/ |
| BullMQ workers, Flowcraft flows | orchestrator/ |
| CLI and agent tooling | agent/, sdk/ |
| Shared types and utilities | common/ |
Follow the conventions in this section — especially Security guidelines and RBAC when touching auth, secrets, or route access.
Database migrations
If you add or rename SQL under backend/supabase/db/, follow the migration naming pattern and re-aggregate before opening the PR:
pnpm backend:db:aggregate-migrations-allSee Database & migrations for push and typegen commands.
Run checks locally
From the repository root, run the checks that apply to your change before you push. Full command reference: Development environment.
Backend — lint and tests:
pnpm backend:lint
pnpm backend:test:unitRun integration or e2e suites when your change touches routes, providers, or cross-module behavior:
pnpm backend:test:integration
pnpm backend:test:e2eWeb — typecheck (and lint when you changed Svelte or TypeScript under web/):
pnpm web:check
pnpm --filter ./web lintOrchestrator / agent — when you changed worker or CLI code:
pnpm orchestrator:test:unit
pnpm agent:test:unitStart the dev servers to manually verify UI or API behavior:
pnpm backend:dev
pnpm web:devCommit and push
Stage only the files you changed, write a clear commit message, and push to your fork:
git add backend/ web/
git commit -m "feat: describe your change briefly"
git push -u origin feat/your-topicCommit message style
Use a conventional prefix (feat:, fix:, chore:, refactor:) and focus on why the change helps users or maintainers, not just which files moved.
Open a pull request
On GitHub, open a pull request from your branch into main on Ratimon/openquok-monorepo.
In the PR description:
- Summarize what you changed and who it helps (dashboard users, API consumers, self-hosters, etc.).
- Link any related issue if one exists.
- Note which packages you touched (backend/, web/, migrations, etc.).
- Add a short Test plan checklist (for example: “Ran
pnpm backend:test:unit”, “Verified OAuth connect flow locally”, “Re-aggregated migrations”).
Maintainers will review, suggest edits if needed, and merge when ready.
What to contribute
Good first contributions include bug fixes, test coverage, provider improvements, UI polish, and documentation clarifications in code comments or README sections.
Larger features (new social providers, new API surfaces) are welcome — open a GitHub issue first if you are unsure about scope. For a new channel integration, start with Adding a social provider.
Documentation-only changes
Edits under web/src/content/docs/ belong in documentation-focused PRs. See Submit a pull request (docs) for the docs workflow and keep code and docs in separate PRs when possible.