PrimeAgent Contribution Workflow: A Complete Guide to Contributing Code

PrimeAgent follows a conventional open-source contribution process with automated CI validation that requires forking the repository, installing Node dependencies with npm install, creating feature branches, adhering to strict TypeScript rules defined in AGENTS.md, running package-specific Vitest tests, and submitting pull requests that trigger comprehensive checks via .github/workflows/ci.yml.

PrimeAgent is an open-source AI agent framework developed by PrimeIntellect-ai. Understanding the PrimeAgent contribution workflow ensures your pull requests pass automated validation and align with the project's strict TypeScript standards. This guide walks through the exact steps documented in packages/coding-agent/docs/development.md and enforced by the repository's continuous integration pipelines.

Fork and Clone the Repository

Start by creating your own fork of the repository on GitHub, then clone it locally.

git clone https://github.com/PrimeIntellect-ai/prime-agent.git
cd prime-agent

Set Up the Development Environment

PrimeAgent uses a monorepo workspace layout managed by npm. Install all dependencies and verify the TypeScript configuration immediately.

npm install          # installs all packages across the monorepo

npm run check        # full TypeScript type-check (fails on any error)

The npm run check command performs a repository-wide type validation. This same check runs in CI, so running it locally prevents downstream failures.

Create a Feature Branch

Always work in isolated branches rather than main. Use descriptive branch names that indicate the purpose of your change.

git checkout -b fix-ai-model-lookup

Follow Development Rules and Coding Standards

PrimeAgent enforces strict code quality rules documented in [AGENTS.md](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md). Key constraints include:

• No inline imports – All imports must appear at the top of the file
• No any types – Strict typing is required unless absolutely unavoidable
• Explicit file staging – Only commit files you specifically touched

Edit source files within the appropriate package directory. For example, when modifying the OpenAI provider, you would edit packages/ai/src/providers/openai.ts.

Run Package-Specific Tests

Each package contains its own Vitest configuration. Run only the tests relevant to your changes to verify functionality before committing.

cd packages/ai
npx tsx ../../node_modules/vitest/dist/cli.js --run test/zen.test.ts

This command executes Vitest directly through tsx, ensuring TypeScript files are processed correctly without separate compilation steps.

Commit Changes Explicitly

The repository requires explicit staging of individual files rather than bulk git add . operations. Write clear, conventional commit messages.

git add packages/ai/src/providers/openai.ts
git commit -m "fix(ai): correct model-id mapping for OpenAI provider"

The .husky/pre-commit hook automatically enforces formatting and linting standards before finalizing your commit.

Submit Your Pull Request

Push your branch to your fork and open a Pull Request against the main repository.

git push origin fix-ai-model-lookup

Once submitted, two automated workflows validate your contribution:

• .github/workflows/ci.yml – Runs npm run check, executes package tests, and validates linting rules
• .github/workflows/build-binaries.yml – Verifies that release scripts still produce functional binaries

Address any CI feedback by pushing additional commits to the same branch. The PR will automatically update.

Merge Requirements

Once your PR receives approval and all checks pass, it becomes eligible for merge. Include fixes #<issue_number> in your commit message to automatically close associated issues upon merge.

Summary

• Fork and clone PrimeIntellect-ai/prime-agent to your local machine
• Run npm install and npm run check to validate the environment
• Create short-lived feature branches for all changes
• Observe strict TypeScript rules from AGENTS.md (no any types, no inline imports)
• Execute package-level Vitest tests using npx tsx before committing
• Stage files explicitly with git add <specific-file> rather than bulk commands
• Submit PRs that trigger automated validation via .github/workflows/ci.yml

Frequently Asked Questions

What are the coding standards for PrimeAgent contributions?

PrimeAgent requires strict TypeScript compliance as defined in AGENTS.md. Contributors must avoid any types unless strictly necessary, place all imports at the top of files (no inline imports), and ensure all code passes the repository-wide type-check via npm run check. The .husky/pre-commit hook enforces formatting automatically before commits are created.

How do I run tests for a specific package?

Navigate to the package directory and execute Vitest through tsx. For example, to test the AI package, run cd packages/ai followed by npx tsx ../../node_modules/vitest/dist/cli.js --run test/zen.test.ts. Only tests touching your changed code need execution during development, though the full suite runs in CI.

What CI checks run on my pull request?

Every PR triggers .github/workflows/ci.yml, which runs npm run check for TypeScript validation, executes package-specific tests, and validates linting. Additionally, .github/workflows/build-binaries.yml verifies that release scripts produce functional binaries. Both workflows must pass before merge.

Where is the detailed development documentation located?

The comprehensive development guide resides at packages/coding-agent/docs/development.md, referenced from the top-level README. This document explains how to run the daemon locally, configure the pre-commit hook, add new unit tests, and navigate the monorepo workspace structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}