# How to Contribute to the PrimeAgent Codebase: A Complete Guide for Developers

> Learn how to contribute to the PrimeAgent codebase with this developer guide. Understand the six-layer architecture and start contributing effectively to the PrimeIntellect-ai/prime-agent repository.

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

---

**Contributing to PrimeAgent requires understanding its six-layer architecture—terminal UI, daemon supervisor, session workers, RLM runtime, model providers, and persistent storage—before modifying any code.**

PrimeAgent is a modular AI coding agent system developed by Prime Intellect. Whether you're adding a new model provider, improving test coverage, or fixing bugs, this guide walks you through the codebase structure and contribution workflow based on the actual source code in the `PrimeIntellect-ai/prime-agent` repository.

## PrimeAgent Architecture Overview

PrimeAgent separates concerns across six core layers. Each layer lives in a specific directory and communicates through well-defined interfaces.

### Daemon Supervisor (`packages/coding-agent/src/supervisor/`)

The **Supervisor** class handles three critical responsibilities:

- **Discovery** – Locates available session workers
- **Routing** – Directs client requests to appropriate workers
- **Recovery** – Restarts failed workers and maintains session state

The supervisor ties together the client-side connection, a catalog of saved sessions, and the worker processes. This is your entry point for understanding how PrimeAgent orchestrates distributed agent sessions.

### Session Worker and RLM Runtime

Each **session worker** runs an `AgentSessionRuntime` that owns:

- A root `AgentSession` (the RLM runtime instance)
- A scheduler for managing execution order
- An IPython kernel for code execution

Workers run isolated from the UI but are not fully sandboxed—security considerations apply when executing arbitrary code.

The **RLM runtime** (`AgentSession`) is the recursive language model core. It handles:

- Model stream processing
- Tool call execution
- Sub-agent creation and management
- Goal tracking and decomposition
- Transcript persistence to JSONL

### Model Provider System (`packages/ai/src/providers/`)

Model providers connect the RLM runtime to external AI services. The provider system uses **lazy registration** to minimize startup overhead.

Key files for provider contributions:

| File | Purpose |
|------|---------|
| [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts) | Lazy registration of all built-in providers |
| [`packages/ai/src/providers/env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/env-api-keys.ts) | Credential detection from environment variables |
| [`packages/ai/scripts/generate-models.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/scripts/generate-models.ts) | Generates [`models.generated.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/models.generated.ts) from provider metadata |

Providers are loaded on-demand through the `lazyProvider` utility—no static imports at startup.

### Persistent Storage (`packages/coding-agent/src/storage/`)

Session transcripts and artifacts are stored as **JSONL files** for append-only durability. The storage layer handles versioning, compaction, and recovery of long-running agent sessions.

For visual reference, see the [Architecture Overview](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) in the repository.

## Common Contribution Paths

### Adding a New AI Provider

Follow these steps to integrate a new model provider into PrimeAgent:

1. **Create provider implementation** in `packages/ai/src/providers/<name>.ts`
2. **Export streaming functions** (`stream`, `streamSimple`) with standardized signatures
3. **Register lazily** in [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts)
4. **Add credential detection** in [`packages/ai/src/providers/env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/env-api-keys.ts)
5. **Generate model metadata** by running `npx tsx scripts/generate-models.ts`

**Example: Minimal Provider Implementation**

```typescript
// packages/ai/src/providers/my-provider.ts
import { stream, streamSimple } from "./my-provider";
export { stream, streamSimple };

```

**Example: Lazy Registration**

```typescript
// packages/ai/src/providers/register-builtins.ts
import { lazyProvider } from "../lazy-loader";

// Register without static import—loaded only when used
lazyProvider("my-provider", async () => import("./my-provider"));

```

### Writing and Running Tests

All packages use **Vitest** for testing. Test files live alongside source code, not in a separate directory.

**Running a specific test:**

```bash
npx tsx ../../node_modules/vitest/dist/cli.js --run packages/ai/test/stream.test.ts

```

**Example: Provider Test Template**

```typescript
// packages/ai/test/my-provider.test.ts
import { test, expect } from "vitest";
import { stream } from "../src/providers/my-provider";

test("my-provider returns text", async () => {
  const result = await stream({ model: "my-model", prompt: "Hello" });
  expect(result.events).toContainEqual({ 
    type: "text", 
    text: expect.any(String) 
  });
});

```

Existing tests in [`packages/ai/test/stream.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/test/stream.test.ts) define the contract that all providers must satisfy. Run these as regression tests when modifying core streaming logic.

### Documentation Updates

User-facing documentation lives in `packages/coding-agent/docs/`:

- [`architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/architecture.md) – System diagrams and component relationships
- [`development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/development.md) – Build instructions and contributor setup

When adding features, update the relevant markdown file and ensure the README's table of contents references your change.

### Bug Fixes and Refactoring

For targeted changes:

- Modify only files directly related to the issue
- Follow strict Git staging rules: use explicit paths, never `git add -A`
- Include `fixes #<issue>` in commit messages for automatic linking

## Essential Files for Contributors

| Path | Purpose | Why It Matters |
|------|---------|--------------|
| [`README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md) | Project overview and quickstart | Entry point for all contributors |
| [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) | System design documentation | Required reading before structural changes |
| [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts) | Provider registration hook | Modify to add new AI backends |
| [`packages/ai/src/models.generated.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/models.generated.ts) | Auto-generated model registry | Regenerate via script, never edit manually |
| [`packages/ai/scripts/generate-models.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/scripts/generate-models.ts) | Model metadata generator | Run after adding provider options |
| [`packages/ai/test/stream.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/test/stream.test.ts) | Core streaming test suite | Validates provider implementations |
| [`packages/ai/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts) | Public API surface | Check for breaking changes |

## Development Workflow

1. **Fork and branch** – Create a feature branch from `main`
2. **Install dependencies** – `npm install` at repository root
3. **Type-check** – `npm run check` catches TypeScript errors early
4. **Test locally** – Run relevant Vitest commands for your changes
5. **Commit with references** – Use `fixes #<issue>` for automatic linking
6. **Push and PR** – Ensure CI passes before requesting review

The repository enforces strict commit hygiene to maintain compatibility across multiple concurrent agent contributions.

## Summary

- **PrimeAgent's six-layer architecture** separates UI, supervision, workers, RLM runtime, providers, and storage
- **New providers** require implementation, lazy registration in [`register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/register-builtins.ts), credential detection in [`env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/env-api-keys.ts), and model generation via [`scripts/generate-models.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/generate-models.ts)
- **Tests use Vitest** and live beside source files—run with explicit file paths, not glob patterns
- **Documentation** spans `packages/coding-agent/docs/` and must stay synchronized with code changes
- **Strict Git practices** (explicit staging, referenced commits) prevent merge conflicts in multi-agent workflows

## Frequently Asked Questions

### Where do I start if I want to add a new AI model provider?

Start with [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts) to understand the lazy loading pattern, then create your provider implementation in a new file under `packages/ai/src/providers/`. You must also update [`env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/env-api-keys.ts) for credential detection and run [`scripts/generate-models.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/generate-models.ts) to populate the model registry.

### How do I run tests for a specific package or file?

Use Vitest directly with explicit paths: `npx tsx ../../node_modules/vitest/dist/cli.js --run <test-file>`. Avoid global test commands—PrimeAgent's modular structure requires targeted test execution.

### Can I manually edit [`models.generated.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/models.generated.ts)?

No. This file is auto-generated by [`packages/ai/scripts/generate-models.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/scripts/generate-models.ts). Edit your provider's metadata and run the generation script instead. Manual changes will be overwritten on the next build.

### What's the difference between the daemon supervisor and the RLM runtime?

The **supervisor** (`Supervisor` class in `packages/coding-agent/src/supervisor/`) manages worker processes at the infrastructure level—discovery, routing, and recovery. The **RLM runtime** (`AgentSession`) executes the actual agent logic: model calls, tool use, and goal decomposition. They operate at different abstraction layers.