Contributing

Thanks for your interest in contributing! VibeXP is an open-source AI workspace (prompts, artifacts, memories, teams, MCP). This page covers how to get a local development environment running. For the full, always-current details, see the repository’s CONTRIBUTING.md.

Prerequisites

• Node.js >= 20 (for the JS/TS workspaces)
• Go (see backend-api/go.mod for the required version) for the backend
• Docker + Docker Compose (for the database and the self-host stack)
• Optionally Bun for the CLI

Clone and install

VibeXP is a flat npm-workspaces monorepo. A fresh install needs no auth token — the shared @vibexp/* packages are vendored in-repo and resolve locally.

git clone https://github.com/shaharia-lab/vibexp-oss.git
cd vibexp-oss

# Installs every JS/TS workspace. No NODE_AUTH_TOKEN or private registry needed.
npm install

Note

If npm install ever asks for credentials, something is misconfigured — there are no private dependencies. The root .npmrc only sets legacy-peer-deps=true.

Run the dev servers

The most common dev loop runs the backend and frontend with hot reload, driven through the root Makefile:

make backend-run-dev    # Go API with live reload
make frontend-run-dev   # React + Vite dev server

Run make help (or open the Makefile) to see all available targets, including:

make backend-build              # compile the backend
make backend-test               # run backend tests
make backend-lint               # golangci-lint
make backend-validate-openapi   # validate the OpenAPI spec

For the JS/TS workspaces:

# Build / lint / type-check a single workspace
npm run build --workspace=frontend
npm run lint --workspace=frontend
npm run typecheck --workspace=frontend

Run the whole stack

For an end-to-end local environment, use the self-host compose file:

docker compose -f docker-compose.selfhost.yml up

See Self-Hosting for the full environment-variable matrix and prerequisites.

Pull requests

1. Fork the repo and create a topic branch off main.
2. Keep your change focused. Add or update tests where it makes sense.
3. Run the relevant lint / test / build commands locally before pushing.
4. Open a PR using the template — fill in What / Why and link any related issue with Closes #123 (or Part of #123 for partial work).

Conventional Commits

We use Conventional Commits for commit messages and PR titles:

feat(frontend): add team switcher to the sidebar
fix(backend-api): return 404 instead of 500 for missing artifacts
docs(docs-site): document the MCP setup flow
chore(cli): bump dependencies

Common types: feat, fix, docs, chore, refactor, test, ci, perf.

GitHub Actions — SHA-pin requirement

All external actions referenced in workflow files (uses:) must be pinned to a full 40-character commit SHA, with the human-readable tag in a trailing comment. Mutable tag references (@v4, @main, …) are not allowed.

# correct
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2

# rejected
- uses: actions/checkout@v6

Internal reusable workflows referenced by path (uses: ./.github/...) are exempt.

Licensing

VibeXP is open-core. When you add files, follow the license of the directory they live in — see Open Source → License model.

Security

Please do not report security vulnerabilities through public GitHub issues. See the repository’s SECURITY.md for the private disclosure process.

Code of Conduct

This project adheres to the Contributor Covenant. By participating, you are expected to uphold it — see the repository’s CODE_OF_CONDUCT.md.