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

> Learn how to contribute to the PrimeAgent open-source project. Follow our guide to fork the repo, set up your environment, code, test, and submit pull requests.

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

---

**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), 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](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 the 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** 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

```bash
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:

```bash
npm ci

```

### Launch the Terminal UI

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

```bash
./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

```bash
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:

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

```

Replace [`specific.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/CHANGELOG.md)

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

### Changelog Entry Format

```markdown

## [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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts) | Register the new provider |
| [`packages/ai/CHANGELOG.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/CHANGELOG.md) | Document the addition |

### Fix a Worker Bug

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) for session queue and tool management, or [`packages/coding-agent/src/core/scheduler.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md) | High-level overview, install instructions, quickstart |
| [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) | Full contribution policy, coding standards, Git workflow |
| [`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 documentation |
| [`packages/coding-agent/docs/development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md) | Local setup, testing, and validation procedures |
| [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) | Core type definitions for providers and model options |
| [`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 (queues, tools, 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 driving autonomous turns and heartbeats |
| [`packages/coding-agent/docs/daemon.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh) and validate with `npm run check`
- **Follow [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/register-builtins.ts), and update the types in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts). The provider must return an `AssistantMessageEventStream` from its streaming function.