Contributing

July 29, 2026 · View on GitHub

Thanks for your interest in contributing to Open Multi-Agent! This guide covers the basics to get you started.

Setup

git clone https://github.com/open-multi-agent/open-multi-agent.git
cd open-multi-agent
npm install

Requires Node.js >= 22.

Development Commands

npm run build          # Compile every workspace
npm run dev            # Watch-mode compilation for @open-multi-agent/core
npm run lint           # Type-check every workspace (tsc --noEmit)
npm test               # Run unit tests in every workspace
npm run test:watch     # Core Vitest watch mode
npm run test:coverage  # Core unit tests with coverage
npm run test:scaffold  # End-to-end create-oma-app scaffold smoke test

Running Tests

Unit tests live in each workspace's tests/ directory: currently packages/core/tests/, packages/create-oma-app/tests/, and packages/otel/tests/. They run without API keys or network access — provider SDKs and external processes are mocked where needed.

npm test

Core E2E tests are separate because they require RUN_E2E=1 and real provider credentials. Each provider suite runs only when its matching credential is present, so a single-key canary does not fail on unrelated providers:

# Runs only the suites whose credentials are set.
# Supported keys: OPENAI_API_KEY, ANTHROPIC_API_KEY,
# GEMINI_API_KEY / GOOGLE_API_KEY, and DEEPSEEK_API_KEY.
npm run test:e2e

Set DEEPSEEK_E2E_MODEL to override the DeepSeek canary model; it defaults to deepseek-v4-flash.

The Provider Canary workflow runs the DeepSeek suite daily and can also be started manually. Maintainers must configure DEEPSEEK_API_KEY as a GitHub Actions repository secret; never add a provider credential to source files or workflow YAML.

Run checks that match the surface you changed and record the commands and results in the PR description. For code changes, start with npm run lint && npm test; also run npm run build when package output or public entry points may be affected, and npm run test:scaffold when changing create-oma-app scaffolding or templates.

CI is the source of truth for the full pre-merge matrix. It runs lint, unit tests on Node 20/22/24, coverage, workspace builds, package/import smoke tests, template type-checking, tarball assertions, and the scaffold E2E test.

Making a Pull Request

  1. Fork the repo and create a branch from main
  2. Make your changes
  3. Add or update tests and user-facing documentation when behavior changes
  4. Run the checks relevant to your change and note any skipped checks with a reason
  5. Open a PR against main

PR Checklist

  • Tests cover changed behavior, or the PR explains why tests are not needed
  • User-facing documentation and examples are updated, or marked not applicable
  • Compatibility, breaking changes, and migration requirements are documented, or marked not applicable
  • Dependency changes are justified and follow the package-specific rules below
  • The PR links a relevant issue when one exists

Code Style

  • TypeScript strict mode, ES modules (.js extensions in imports)
  • No additional linter/formatter configured — follow existing patterns
  • Keep dependency ownership explicit. Core must remain importable and runnable without optional integrations
  • Add new optional provider SDKs as peer dependencies and load them lazily with dynamic import()
  • Keep OpenTelemetry APIs, SDKs, semantic-convention packages, and exporters in @open-multi-agent/otel, never in the core root import
  • Version @open-multi-agent/otel independently from core and express core compatibility in its dependency range
  • Justify dependency changes to other workspaces in the PR description

Architecture Overview

See the README for an architecture diagram. Key entry points:

  • Orchestrator: packages/core/src/orchestrator/orchestrator.ts — top-level API
  • Task system: packages/core/src/task/queue.ts, packages/core/src/task/task.ts — dependency DAG
  • Agent: packages/core/src/agent/runner.ts — conversation loop
  • Tools: packages/core/src/tool/framework.ts, packages/core/src/tool/executor.ts — tool registry and execution
  • LLM adapters: packages/core/src/llm/ — built-in providers + OpenAI-compatible + AI SDK bridge (see docs/providers.md)
  • Observability: packages/core/src/observability/ — trace records, sinks, exporters, and stores
  • OpenTelemetry adapter: packages/otel/src/ — optional OTel mapping and export integration kept outside core
  • App scaffolder: packages/create-oma-app/src/ and packages/create-oma-app/templates/ — CLI and starter templates

Where to Contribute

Check the issues page. Issues labeled good first issue are scoped and approachable. Issues labeled help wanted are larger but well-defined.

License

By contributing, you agree that your contributions will be licensed under the MIT License.