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

> Contribute to PrimeAgent by forking the repo, setting up your local environment, and adhering to coding standards. Learn how to submit your pull request today.

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

---

**Fork the PrimeIntellect-ai/prime-agent repository, install Node.js 22.8 or later, run `npm ci` and [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh) to build locally, then follow the coding standards defined in [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) while adding tests and changelog entries before submitting your pull request.**

PrimeAgent is a modular monorepo that combines a terminal UI, daemon-supervisor, session-worker runtime, and LLM providers into a cohesive coding agent system. Whether you are adding support for a new model provider, fixing bugs in the scheduler, or improving documentation, understanding the four-layer architecture is essential for making effective contributions to this PrimeIntellect-ai project.

## Understanding the PrimeAgent Architecture

PrimeAgent follows a strict separation of concerns across four architectural layers defined in [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) and [`packages/coding-agent/docs/daemon.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/daemon.md).

### The Four-Layer Stack

- **Client Layer** – The TUI or headless JSON/RPC client that renders the interface, handles keyboard input, and forwards commands to the supervisor.
- **Supervisor (Daemon)** – Discovers active sessions, routes commands between components, manages file attachments, and recovers crashed workers. Implementation details live in the daemon documentation.
- **Worker Layer** – The `AgentSessionRuntime` owns the root IPython kernel, manages the scheduler, handles child RLM runtimes, and persists conversation transcripts to storage.
- **Provider Layer** – Streams model responses, executes tool calls, and reports token usage. Core type definitions are located in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts).

### Prompt Execution Flow

When a user submits input, the request travels through the client → supervisor → worker → provider → optional IPython kernel → storage → back to the client. This sequence is illustrated in the architecture diagram within [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md), showing exactly how each layer communicates during autonomous execution.

## Setting Up Your Development Environment

Contributing to PrimeAgent requires a specific toolchain and build process to ensure consistency across the monorepo.

### Prerequisites and Installation

You need **Node.js 22.8 or higher** installed on your system. Clone your fork and install exact dependencies using the lockfile:

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

```

### Building from Source

The repository includes a wrapper script to launch the TUI directly from source without a global install:

```bash
./prime-agent.sh

```

This command initializes the full client-supervisor-worker stack described in the architecture documentation, allowing you to test changes immediately in an interactive terminal session.

## Development Workflow and Testing

PrimeAgent maintains quality through comprehensive integration tests and strict code quality gates.

### Running the Test Suite

All tests execute against a faux provider implementation, meaning **no real API keys are required**. After making changes, run the repository-wide validation:

```bash
npm run check

```

This command executes formatting, linting, and type-checking across all packages. For focused testing on specific modules, navigate to the package directory and use Vitest directly:

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

```

*All new tests must pass before a pull request is merged.*

### Code Quality Standards

According to [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md), contributors must adhere to these rules:
- Never use the `any` type unless absolutely unavoidable.
- Run `npm run check` after every change to verify formatting and types.
- Include a `fixes #<issue>` or `closes #<pr>` footer in commit messages for traceability.

## Contribution Guidelines and Standards

The [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) file at the repository root contains the complete contribution policy, including Git workflow and changelog requirements.

### Changelog and Commit Format

Every pull request must include a one-line entry under the `## [Unreleased]` section of each modified package’s [`CHANGELOG.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/CHANGELOG.md). Example entry:

```markdown

## [Unreleased]

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

```

Commit messages should follow conventional commit format, such as `feat(ai): add MyProvider support`, and include the appropriate issue reference footer.

## Common Contribution Scenarios

Different contribution types require touching specific files within the monorepo structure.

### Adding LLM Providers

To integrate a new model provider, modify:
- [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) – Core type definitions
- `packages/ai/src/providers/<new>.ts` – Your provider implementation
- [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts) – Registration logic
- [`packages/ai/CHANGELOG.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/CHANGELOG.md) – Version documentation

Implement a `streamMyProvider()` function that returns an `AssistantMessageEventStream` according to the provider interface defined in the types file.

### Worker and Scheduler Changes

For modifications to the execution runtime, 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) – Central `AgentSession` implementation handling queues, tools, and compaction
- [`packages/coding-agent/src/core/scheduler.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/scheduler.ts) – Scheduler logic that drives autonomous turns and heartbeat intervals

These files manage the back-pressure logic and runtime state persistence critical to long-running agent sessions.

### Documentation Updates

Improvements to guides and architecture explanations belong in `packages/coding-agent/docs/*.md`. When adding features, update the relevant markdown files to reflect new capabilities, ensuring the sequence diagrams and execution flow descriptions remain accurate.

## Summary

- **PrimeAgent uses a four-layer architecture** (Client, Supervisor, Worker, Provider) documented in [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md).
- **Node.js 22.8+ and `npm ci`** are required to build the project from source using [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh).
- **`npm run check`** enforces formatting, linting, and type-checking standards defined in [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md).
- **All changes require tests** using Vitest and entries in the relevant [`CHANGELOG.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/CHANGELOG.md) under `## [Unreleased]`.

- **New providers** implement the interface in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) and register in [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts).

## Frequently Asked Questions

### What Node.js version is required to contribute to PrimeAgent?

You need **Node.js 22.8 or higher** to ensure compatibility with the build system and dependency tree. The `npm ci` command will fail on older versions due to package constraints.

### How do I run tests for a specific package without executing the entire suite?

Navigate to the package directory and run `npx tsx ../../node_modules/vitest/dist/cli.js --run test/<filename>.test.ts`. This executes only the specified test file against the faux provider, requiring no external API keys.

### Where do I document my changes before submitting a pull request?

Add a one-line entry under the `## [Unreleased]` section of each modified package’s [`CHANGELOG.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/CHANGELOG.md). For example, if you modified the AI package, update [`packages/ai/CHANGELOG.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/CHANGELOG.md) with a concise description of your change and the relevant file path.

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

Create a new file in `packages/ai/src/providers/<provider-name>.ts` implementing the `stream` function that returns an `AssistantMessageEventStream`, then register the provider in [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts). Update [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) if your provider requires new type definitions, and document the addition in [`packages/ai/CHANGELOG.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/CHANGELOG.md).