Skip to main content
Vibra Code is an open-source project and contributions are welcome. Whether you’re fixing a bug, improving the native iOS chat UI, or adding a new template, this guide covers everything you need to go from zero to an open pull request.
By contributing to Vibra Code, you agree that your contributions will be licensed under the AGPL-3.0 License. If your employer has rights to code you write, make sure you have permission to contribute under AGPL-3.0 before opening a PR.

​
Prerequisites

Before you begin, make sure you have the following installed:
RequirementVersionPurpose
Node.js20+Backend runtime
YarnanyMobile app dependency management
Xcode16+iOS simulator and native builds
CocoaPodslatestiOS native dependency management
GitanyVersion control
Install CocoaPods if you don’t have it: 
gem install cocoapods
You will also need API keys for the core services (Anthropic, E2B, Clerk, Convex) to run the full stack locally. See the self-hosting quickstart for details on obtaining these keys.

​
Contribution workflow

1

Fork and clone the repository

Fork the repository on GitHub, then clone your fork with submodules:
git clone --recurse-submodules https://github.com/YOUR_USERNAME/vibra-code.git
cd vibra-code
Create a feature branch from main:
git checkout -b feat/my-feature
2

Set up the backend

cd vibracode-backend
npm install
cp .env.example .env.local
Fill in the required variables in .env.local:
ANTHROPIC_API_KEY=
E2B_API_KEY=
NEXT_PUBLIC_CONVEX_URL=
CONVEX_DEPLOYMENT=
CLERK_SECRET_KEY=
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
Deploy the Convex schema (first time only):
npx convex deploy
Start the full backend stack:
npm run start   # Next.js + Inngest dev server together
Or start them separately:
npm run dev                    # Next.js only → localhost:3000
npx inngest-cli@latest dev     # Inngest only → localhost:8288
3

Set up the mobile app

cd vibracode-mobile/apps/expo-go
Create the environment file:
# vibracode-mobile/apps/expo-go/.env
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=
EXPO_PUBLIC_CONVEX_URL=
EXPO_PUBLIC_V0_API_URL=http://localhost:3000
Install JavaScript dependencies:
yarn install
If you’re working on iOS native code, install CocoaPods:
cd ios && pod install && cd ..
Start the Metro bundler (must run on port 80):
yarn start
Then open ios/Exponent.xcworkspace in Xcode. In EXBuildConstants.plist, set DEV_KERNEL_SOURCE to LOCAL. Build and run to a simulator or device.
4

Make your changes

Work on your feature or fix. Follow the code style guidelines below. Write focused commits with clear messages:
git add .
git commit -m "feat: add support for custom sandbox timeout"
5

Run tests and linting

Before opening a PR, verify everything passes:
# Mobile tests and lint
cd vibracode-mobile/apps/expo-go
yarn test
yarn lint

# Backend lint
cd vibracode-backend
npm run lint
6

Open a pull request

Push your branch and open a PR against main on the upstream repository. Your PR description should include:
  • A clear title describing the change
  • What changed and why
  • Screenshots or screen recordings for any UI changes
  • A link to the related issue, if applicable
Address any review feedback promptly. Once approved, a maintainer will merge your PR.

​
Code style guide

​
TypeScript (backend and React Native)

Use TypeScript for all new backend and React Native code. Follow the patterns already established in the codebase:
  • Backend (Next.js): Convex functions follow the schema patterns in convex/schema.ts. Inngest functions handle background processing and live in lib/inngest/functions/. API routes use Next.js App Router conventions.
  • React Native: Components live in src/screens/ (screens) and src/services/ (business logic). Use the same import aliases and hook patterns as existing files.
  • Convex schema is shared between the mobile app and backend via a symlink — do not duplicate it.

​
Objective-C (iOS native Menu system)

The native iOS chat UI in apps/expo-go/ios/Client/Menu/ is written in Objective-C and must stay that way. Key rules:
  • All chat cell nodes extend ASCellNode (Texture/AsyncDisplayKit)
  • Layout uses ASLayoutSpec, not Auto Layout
  • Image loading uses SDWebImage
  • Animations use spring timing: UIView.animate(springDuration:)
  • Target iOS 26+ with modern APIs (prefer UIGlassEffect over UIBlurEffect, etc.)

​
PR guidelines

  • Keep PRs focused. One concern per PR. A PR that fixes a bug should not also refactor unrelated code.
  • No mixed refactors. If you want to refactor something while fixing a bug, open a separate PR for the refactor.
  • Update documentation. If your change affects user-facing behavior, update the relevant docs page.
  • Add tests for new functionality. If you add a new function or feature, include test coverage.

Build docs developers (and LLMs) love

Get started for freeTalk to us