Skip to content

Contributing to Hybrid

Thanks for your interest in contributing to Hybrid! This guide will help you get up and running quickly.

Quick Start

Prerequisites

  • Node.js 22 (required)
  • pnpm (package manager)
  • Git

Setup

# 1. Fork and clone the repo
git clone https://github.com/YOUR_USERNAME/hybrid.git
cd hybrid
 
# 2. Install dependencies
pnpm install
 
# 3. Build all packages
pnpm build
 
# 4. Run tests to make sure everything works
pnpm test

Testing Your Setup

Set up an example agent to test your changes:

cd examples/basic
 
# Create .env file
cat > .env << EOF
OPENROUTER_API_KEY=your_key_here
XMTP_ENV=dev
EOF
 
# Generate XMTP keys
pnpm hybrid keys --write
 
# Start the agent
pnpm dev

Test by sending a message to your agent at xmtp.chat.

Making Changes

Common Workflows

Working on core package: 
# Make your changes in packages/core/src/
cd packages/core
 
# Build and watch for changes
pnpm build:watch
Working on CLI: 
# Make your changes in packages/cli/src/
cd packages/cli
 
# Test CLI commands
pnpm build
cd ../../examples/basic
pnpm hybrid dev
Working on XMTP integration: 
# Make your changes in packages/xmtp/src/
cd packages/xmtp
 
# Build and test
pnpm build:watch

Project Structure

hybrid/
├── packages/
│   ├── core/           # Main framework (published as "hybrid")
│   ├── cli/            # CLI tool (bin: "hybrid")
│   ├── xmtp/           # XMTP integration (@hybrd/xmtp)
│   └── utils/          # Utilities (@hybrd/utils)
├── examples/
│   └── basic/          # Example agent for testing
└── site/               # Documentation

Code Guidelines

Style

We use Biome for formatting and linting. Just run:

pnpm lint:fix

Key Patterns

  • ✅ Use interfaces over types for object shapes
  • ❌ Never use any - use unknown instead
  • ❌ No enums - use const objects with as const
  • Files/folders: kebab-case
  • Classes/interfaces: PascalCase
  • Functions/variables: camelCase

Testing

Add tests for new features:

# Run all tests
pnpm test
 
# Run tests for a specific package
cd packages/core
pnpm test

We use Vitest. Put tests next to your code or in a test/ directory.

Submitting Your Changes

Before You Submit

# 1. Format and lint
pnpm lint:fix
 
# 2. Check types
pnpm typecheck
 
# 3. Run tests
pnpm test
 
# 4. Build everything
pnpm build
 
# 5. Test manually
cd examples/basic
pnpm dev

Creating a Pull Request

  1. Branch naming:
    • feature/your-feature - New features
    • fix/the-bug - Bug fixes
    • docs/what-changed - Documentation
  2. Commit format: 
    feat(core): add new behavior system
fix(xmtp): resolve connection timeout
docs(readme): update quickstart guide
  3. PR description:
    • What does this change?
    • Why is it needed?
    • How did you test it?
    • Any breaking changes?

What Happens Next

  • CI runs tests and type checks
  • A maintainer will review your PR
  • We might ask for changes
  • Once approved, we'll merge it!

Reporting Issues

Found a bug? Open an issue with:

  • What you expected to happen
  • What actually happened
  • Steps to reproduce
  • Your environment (OS, Node version, Hybrid version)

Have an idea? Start a discussion first!

Getting Help

Need help contributing?

  1. Check the documentation
  2. Search existing issues
  3. Ask in GitHub Discussions
  4. Join our Discord (link in README)

Development Tips

Useful Commands

pnpm build              # Build all packages
pnpm build:watch        # Build in watch mode
pnpm build:packages     # Build only packages (skip examples)
pnpm test               # Run all tests
pnpm lint               # Check code style
pnpm lint:fix           # Fix code style
pnpm typecheck          # Check TypeScript types
pnpm clean              # Clean build artifacts
pnpm nuke               # Nuclear option - delete all node_modules

Working with the Monorepo

The project uses pnpm workspaces and Turbo. Changes to packages automatically rebuild dependent packages when using build:watch.

Testing Changes Locally

Link your local version to test in other projects:

cd packages/core
pnpm link --global
 
cd ~/your-project
pnpm link --global hybrid

Environment Variables

For testing, create .env in examples/basic/:

OPENROUTER_API_KEY=your_key
XMTP_WALLET_KEY=0x...
XMTP_DB_ENCRYPTION_KEY=...
XMTP_ENV=dev
PORT=8454

Generate XMTP keys with: pnpm hybrid keys --write

Code of Conduct

Be respectful, inclusive, and constructive. We're building this together!

  • Use welcoming and inclusive language
  • Be respectful of differing viewpoints
  • Accept constructive criticism gracefully
  • Focus on what's best for the community

Recognition

Contributors are recognized in:

  • Release notes
  • CONTRIBUTORS.md
  • Documentation credits
  • Social media shoutouts

Next Steps

Ready to contribute? Fork the repo and start hacking! 🚀