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

Fork the PrimeIntellect-ai/prime-agent repository, install Node.js 22.8 or later, run npm ci and ./prime-agent.sh to build locally, then follow the coding standards defined in 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 and 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.

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

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:

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

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:

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, 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 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. Example entry:

## [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 – Core type definitions
• packages/ai/src/providers/<new>.ts – Your provider implementation
• packages/ai/src/providers/register-builtins.ts – Registration logic
• 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 – Central AgentSession implementation handling queues, tools, and compaction
• 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.

• Node.js 22.8+ and npm ci are required to build the project from source using ./prime-agent.sh.

• npm run check enforces formatting, linting, and type-checking standards defined in AGENTS.md.

• All changes require tests using Vitest and entries in the relevant CHANGELOG.md under ## [Unreleased].

• New providers implement the interface in packages/ai/src/types.ts and register in 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. For example, if you modified the AI package, update 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. Update packages/ai/src/types.ts if your provider requires new type definitions, and document the addition in packages/ai/CHANGELOG.md.

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