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

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	Lazy registration of all built-in providers
packages/ai/src/providers/env-api-keys.ts	Credential detection from environment variables
packages/ai/scripts/generate-models.ts	Generates 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 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
4. Add credential detection in packages/ai/src/providers/env-api-keys.ts
5. Generate model metadata by running npx tsx scripts/generate-models.ts

Example: Minimal Provider Implementation

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

Example: Lazy Registration

// 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:

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

Example: Provider Test Template

// 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 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 – System diagrams and component relationships
• 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	Project overview and quickstart	Entry point for all contributors
packages/coding-agent/docs/architecture.md	System design documentation	Required reading before structural changes
packages/ai/src/providers/register-builtins.ts	Provider registration hook	Modify to add new AI backends
packages/ai/src/models.generated.ts	Auto-generated model registry	Regenerate via script, never edit manually
packages/ai/scripts/generate-models.ts	Model metadata generator	Run after adding provider options
packages/ai/test/stream.test.ts	Core streaming test suite	Validates provider implementations
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, credential detection in env-api-keys.ts, and model generation via 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 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 for credential detection and run 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?

No. This file is auto-generated by 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.

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