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

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, 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
Supervisor (Daemon)	Discovers sessions, routes commands, manages attachments, recovers crashed workers	packages/coding-agent/docs/daemon.md
Worker (AgentSessionRuntime)	Owns root IPython kernel, scheduler, child RLM runtimes, persists transcripts	packages/coding-agent/docs/architecture.md
Provider	Streams model responses, handles tool calls, reports usage	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

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

Install Dependencies

npm ci

This runs a lockfile-based install for reproducible builds.

Run PrimeAgent from Source

The repository includes a wrapper script for local development:

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

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:

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. 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

• 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
• packages/ai/src/providers/<new>.ts
• packages/ai/src/providers/register-builtins.ts
• 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
• packages/coding-agent/src/core/scheduler.ts

The AgentSession class in agent-session.ts handles queues, tools, and compaction. The 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	High-level overview and quickstart
AGENTS.md	Full contribution policy and coding standards
packages/coding-agent/docs/architecture.md	Architecture diagram and execution flow
packages/coding-agent/docs/development.md	Local setup and validation steps
packages/ai/src/types.ts	Core provider and model option types
packages/coding-agent/src/core/agent-session.ts	Central AgentSession implementation
packages/coding-agent/src/core/scheduler.ts	Turn scheduler and heartbeat driver
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 to run
• Quality gates: npm run check for linting/formatting, Vitest for testing
• Contribution rules in 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 and 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 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, and update packages/ai/src/types.ts with any new type definitions.

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