How to Contribute to PrimeAgent: A Complete Guide for Open-Source Contributors

To contribute to PrimeAgent, fork the repository, install Node 22.8+, run npm ci to build from source, follow the coding standards in AGENTS.md, add tests, and update the relevant package changelog before submitting your pull request.

PrimeAgent is a modular monorepo developed by PrimeIntellect that combines a terminal UI, daemon-supervisor, session-worker runtime, and LLM providers. This guide walks you through the contribution workflow, architecture, and coding standards required to submit clean, review-ready code to the PrimeAgent project.

Understanding PrimeAgent's Architecture

Before writing code, you need to understand how the four-layer system works. The architecture is documented in packages/coding-agent/docs/architecture.md with detailed sequence diagrams showing how user input flows through the stack.

Layer	Responsibility	Core Source Location
Client – TUI or headless JSON/RPC client	Renders UI, handles keyboard input, forwards commands	packages/coding-agent/docs/architecture.md
Supervisor (Daemon)	Discovers sessions, routes commands, manages attachments, recovers crashed workers	packages/coding-agent/docs/daemon.md
Worker – AgentSessionRuntime	Owns the root IPython kernel, scheduler, child RLM runtimes, persists transcripts	packages/coding-agent/docs/architecture.md
Provider	Streams model responses, handles tool calls, reports usage	packages/ai/src/types.ts

The prompt execution flow traces how input travels: client → supervisor → worker → provider → optional IPython kernel → storage → client. Understanding this flow helps you identify where to make changes for your contribution to PrimeAgent.

Setting Up Your Development Environment

Follow these steps to build PrimeAgent from source and validate your setup.

Fork and Clone the Repository

git clone https://github.com/your-username/prime-agent.git
cd prime-agent

Install Dependencies

PrimeAgent requires Node 22.8 or higher. Use the lockfile-based install for reproducible builds:

npm ci

Launch the Terminal UI

The repository includes a wrapper script to run the CLI from source:

./prime-agent.sh

This command launches the TUI using the full client-supervisor-worker stack.

Running Tests and Validation

PrimeAgent maintains a large integration test suite. All new tests must pass before a PR is merged.

Run Repository-Wide Checks

npm run check

This command executes formatting, linting, and type-checking across all packages.

Run Focused Tests

After modifying code, test the specific components you touched:

cd packages/coding-agent
npx tsx ../../node_modules/vitest/dist/cli.js --run test/specific.test.ts

Replace specific.test.ts with the actual test file matching your changes. The test suite uses a faux provider—no real API keys are required.

Contribution Standards and Rules

The complete contribution policy lives in AGENTS.md at the repository root. Key requirements for PrimeAgent contributors include:

• Never use any unless absolutely unavoidable

• Run npm run check after every change

• Add a one-line entry under ## [Unreleased] in each affected package's CHANGELOG.md

• Include fixes #<issue> or closes #<pr> in your commit message footer

Changelog Entry Format

## [Unreleased]

- Added support for the "MyProvider" LLM (see `packages/ai/src/providers/myprovider.ts`).

Commit with a conventional message like feat(ai): add MyProvider support and include the issue reference.

Common Contribution Scenarios

Add a New LLM Provider

Files to Edit	Example Implementation
packages/ai/src/types.ts	Define provider types and configuration interfaces
packages/ai/src/providers/<new>.ts	Implement streamMyProvider() returning AssistantMessageEventStream
packages/ai/src/providers/register-builtins.ts	Register the new provider
packages/ai/CHANGELOG.md	Document the addition

Fix a Worker Bug

Edit packages/coding-agent/src/core/agent-session.ts for session queue and tool management, or packages/coding-agent/src/core/scheduler.ts for autonomous turn scheduling and heartbeat logic.

Improve Documentation

Add sections to packages/coding-agent/docs/*.md—the "Long-Running Agents" guide or architecture explanations are common targets.

Update Tests

Add regression tests to packages/coding-agent/test/**/*.test.ts for edge cases you've fixed.

Key Files Every Contributor Should Know

File	Purpose
README.md	High-level overview, install instructions, quickstart
AGENTS.md	Full contribution policy, coding standards, Git workflow
packages/coding-agent/docs/architecture.md	Architecture diagram and execution flow documentation
packages/coding-agent/docs/development.md	Local setup, testing, and validation procedures
packages/ai/src/types.ts	Core type definitions for providers and model options
packages/coding-agent/src/core/agent-session.ts	Central AgentSession implementation (queues, tools, compaction)
packages/coding-agent/src/core/scheduler.ts	Scheduler driving autonomous turns and heartbeats
packages/coding-agent/docs/daemon.md	Daemon-supervisor responsibilities and protocol versioning

Summary

• Fork and clone the PrimeIntellect-ai/prime-agent repository
• Install Node 22.8+ and run npm ci for dependencies
• Launch locally with ./prime-agent.sh and validate with npm run check
• Follow AGENTS.md strictly—no any types, proper changelog entries, and issue references
• Test thoroughly using the faux provider suite before submitting PRs
• Update changelogs in affected packages under ## [Unreleased]

Frequently Asked Questions

What Node version does PrimeAgent require?

PrimeAgent requires Node 22.8 or higher. Run node --version before installing dependencies to verify compatibility. The npm ci command will fail on older versions.

Where do I find the complete contribution rules?

The full policy is in AGENTS.md at the repository root. This file covers code style, Git workflow, changelog format, and review requirements. Read it completely before your first contribution.

Do I need API keys to run tests?

No. PrimeAgent's test suite uses a faux provider implementation. No real LLM API keys are required to run npx tsx ../../node_modules/vitest/dist/cli.js --run or the full integration suite.

Which file should I modify to add a new LLM provider?

Create your implementation in packages/ai/src/providers/<new>.ts, register it in register-builtins.ts, and update the types in packages/ai/src/types.ts. The provider must return an AssistantMessageEventStream from its streaming function.

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