# How to Contribute to the PrimeAgent Project: A Complete Developer's Guide

> Learn how to contribute to the PrimeAgent project. Fork the repo, set up your environment, and submit PRs following our developer guide for seamless integration.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md), and submit PRs with tests and changelog updates.**

PrimeAgent is a modular AI agent monorepo developed by Prime Intellect that combines a terminal UI, daemon-supervisor, session-worker runtime, and LLM providers. Understanding its **four-layer architecture** and development workflow is essential for making effective contributions.

## PrimeAgent Architecture Overview

PrimeAgent splits functionality across four coordinated layers. Knowing where your change fits prevents errors and speeds up review.

| Layer | Responsibility | Core Source Location |
|-------|---------------|----------------------|
| **Client** | Renders TUI, handles keyboard input, forwards commands | [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) |
| **Supervisor (Daemon)** | Discovers sessions, routes commands, manages attachments, recovers crashed workers | [`packages/coding-agent/docs/daemon.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/daemon.md) |
| **Worker** (`AgentSessionRuntime`) | Owns root IPython kernel, scheduler, child RLM runtimes, persists transcripts | [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) |
| **Provider** | Streams model responses, handles tool calls, reports usage | [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) |

The **prompt execution flow** documented in the architecture diagram shows how user input travels: **client → supervisor → worker → provider → optional IPython kernel → storage → client**.

## Development Environment Setup

### Prerequisites

- **Node.js 22.8 or higher**

### Fork and Clone

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

```

### Install Dependencies

```bash
npm ci

```

This runs a lockfile-based install for reproducible builds.

### Run PrimeAgent from Source

The repository includes a wrapper script for local development:

```bash
./prime-agent.sh

```

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

### Validate Your Changes

Run the repository-wide quality checks after every modification:

```bash
npm run check

```

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

### Run Focused Tests

PrimeAgent includes a comprehensive integration test suite using **Vitest**:

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

```

All tests run against a **faux provider**—no real API keys required. *All new tests must pass before PR merge.*

## Contribution Standards and Rules

The complete policy lives in **[`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md)**. Key requirements include:

- **Never use `any`** unless absolutely unavoidable
- Run **`npm run check`** after every change
- Add a **one-line entry** under `## [Unreleased]` in each modified package's [`CHANGELOG.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/CHANGELOG.md)

- Include **`fixes #<issue>`** or **`closes #<pr>`** footer in commit messages

## Common Contribution Scenarios

### Add a New LLM Provider

**Files to edit:**
- [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts)
- `packages/ai/src/providers/<new>.ts`
- [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts)
- [`packages/ai/CHANGELOG.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/CHANGELOG.md)

**Implementation pattern:** Create a `streamMyProvider()` function returning `AssistantMessageEventStream`.

### Fix Worker Bugs

**Files to edit:**
- [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts)
- [`packages/coding-agent/src/core/scheduler.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/scheduler.ts)

The `AgentSession` class in [`agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-session.ts) handles queues, tools, and compaction. The [`scheduler.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scheduler.ts) file drives autonomous turns and heartbeats.

### Improve Documentation

Edit files in `packages/coding-agent/docs/*.md`—for example, adding sections to the "Long-Running Agents" guide.

### Update Tests

Add or modify files in `packages/coding-agent/test/**/*.test.ts` to cover regression cases.

## Essential PrimeAgent Source Files

| File | Purpose |
|------|---------|
| [`README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md) | High-level overview and quickstart |
| [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) | Full contribution policy and coding standards |
| [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) | Architecture diagram and execution flow |
| [`packages/coding-agent/docs/development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md) | Local setup and validation steps |
| [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) | Core provider and model option types |
| [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts) | Central `AgentSession` implementation |
| [`packages/coding-agent/src/core/scheduler.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/scheduler.ts) | Turn scheduler and heartbeat driver |
| [`packages/coding-agent/docs/daemon.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/daemon.md) | Supervisor responsibilities and protocol versioning |

## Summary

- **PrimeAgent** uses a four-layer architecture: Client, Supervisor, Worker, and Provider
- **Development setup** requires Node 22.8+, `npm ci`, and [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh) to run
- **Quality gates**: `npm run check` for linting/formatting, Vitest for testing
- **Contribution rules** in [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) ban `any`, require changelog entries, and enforce commit message footers
- **Provider additions** implement `AssistantMessageEventStream` in `packages/ai/src/providers/`
- **Worker changes** focus on [`agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-session.ts) and [`scheduler.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scheduler.ts)

## Frequently Asked Questions

### What Node.js version does PrimeAgent require?

PrimeAgent requires **Node.js 22.8 or higher**. The `npm ci` command installs exact dependencies locked in the repository.

### Where are the coding standards documented?

All coding standards, Git workflow rules, and changelog formatting requirements are in **[`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md)** at the repository root. Critical rules include avoiding `any` types and including issue references in commits.

### Do I need API keys to run PrimeAgent tests?

No. The test suite uses a **faux provider** that simulates LLM responses without requiring real API keys, making local development and CI testing straightforward.

### How do I add a new LLM provider to PrimeAgent?

Implement a streaming function returning `AssistantMessageEventStream` in `packages/ai/src/providers/<your-provider>.ts`, register it in [`register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/register-builtins.ts), and update [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) with any new type definitions.