# How to Contribute to Prime Agent: A Step-by-Step Guide for Open-Source Contributors

> Ready to contribute to Prime Agent? Follow our step-by-step guide to initiate a GitHub Discussion and get invited to submit pull requests to prime-agent.

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

---

**To contribute to Prime Agent, start a GitHub Discussion first—pull requests are accepted by invitation only after maintainers review your proposal.**

Prime Agent is an open-source, self-improving coding and research assistant built around a **recursive language model (RLM)** and a **continual harness** for prompts, memories, and reusable sub-agents. If you want to contribute to PrimeIntellect-ai/prime-agent, you'll need to follow a structured workflow designed to maintain code quality and project stability.

## Understanding the Repository Structure

Prime Agent is organized as a TypeScript monorepo with a Python runtime. Knowing where code lives helps you target your contributions effectively.

| Package | Purpose | Key Files |
|---------|---------|-----------|
| `packages/ai` | Core LLM provider abstraction, streaming, token handling | [`packages/ai/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts), [`packages/ai/README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/README.md) |
| `packages/tui` | Text-based UI rendering chat, keybindings, markdown | [`packages/tui/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts) |
| `packages/agent` | High-level orchestration of agents and daemon communication | [`packages/agent/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts) |
| `packages/coding-agent` | Main CLI, session management, dev utilities | [`packages/coding-agent/docs/development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md) |
| `prime-agent-runtime` | Python runtime hosting the IPython kernel | [`prime-agent-runtime/pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent-runtime/pyproject.toml) |

## The Contribution Workflow

### 1. Start with a GitHub Discussion

The project **does not accept unsolicited pull requests**. Open a Discussion first:

- Choose the appropriate category: **General**, **Bug report**, or **Feature request**
- Describe your problem or idea in detail
- Reference the discussion guidelines in [`CONTRIBUTING.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/CONTRIBUTING.md)

A maintainer may convert your discussion into an Issue and invite you to submit a PR. Only **vouched contributors**—those with demonstrated reliable collaboration—may open pull requests directly.

### 2. Set Up Your Development Environment

Once invited, clone and prepare the repository:

```bash
git clone https://github.com/PrimeIntellect-ai/prime-agent.git
cd prime-agent

# Install Node dependencies (npm ≥ 11.10 required)

npm ci

# Install the Python runtime used by the agent

cd prime-agent-runtime && pip install -e .

```

For detailed setup instructions, see [`packages/coding-agent/docs/development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md).

### 3. Create a Focused Branch

```bash
git checkout -b <your-feature-branch>

```

Name your branch descriptively (e.g., `fix-token-leak`, `feat-anthropic-provider`).

### 4. Make Well-Scoped Changes

Follow the codebase standards when you contribute to PrimeIntellect-ai/prime-agent:

- **No `any` types** unless absolutely unavoidable
- **Lint-free TypeScript**
- **Consistent documentation**

Add or update tests covering new behavior. Reference existing test suites in `packages/ai/test/` and `packages/tui/test/` for patterns.

### 5. Run Repository Checks

After each change, execute the full type-check:

```bash
npm run check

```

Fix all reported errors and warnings before committing. No tests run automatically—you must verify manually.

### 6. Commit with Precision

Stage only files you modified:

```bash
git add packages/ai/src/new-provider.ts
git commit -m "feat(ai): add support for NewProvider"

```

**Never use `git add -A` or `git commit --no-verify`.**

### 7. Push and Open Your PR

When maintainers give approval:

```bash
git push origin your-feature-branch

```

Create a pull request referencing the original discussion or issue:

```

Fixes #123

```

### 8. Iterate on Feedback

Address reviewer comments until your PR passes CI (`npm run check`) and receives final approval. Maintainers handle the merge.

## Key Architectural Areas for Contributors

### Daemon-Worker-Kernel Model

The **daemon** ([`src/daemon.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/daemon.ts)) runs a background service spawning worker processes. Workers host the IPython kernel (`prime-agent-runtime`) and communicate via a serialized protocol defined in [`src/daemon-schema.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/daemon-schema.ts).

Adding new commands or events requires:
- Updating the protocol version
- Modifying compatibility maps

See the *Daemon Protocol Changes* section in [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) for specifications.

### Streaming LLM Provider Abstraction

Providers 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). To add a new LLM provider:

1. Define option types in [`src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/types.ts)
2. Implement streaming functions in `src/providers/<provider>.ts`
3. Export the provider in [`src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/index.ts)
4. Update [`src/env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/env-api-keys.ts) for credential detection

### TUI Rendering Pipeline

The Text UI consumes message events from the daemon and renders markdown, images, and tool calls. Core rendering lives in [`packages/tui/src/render.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/render.ts). When extending UI capabilities, add corresponding test cases in `packages/tui/test/`.

### Testing Strategy

The project uses **Vitest** for unit and integration tests. Each new feature requires at least one test in the appropriate package directory. Run tests locally with:

```bash
npx vitest run <test-file>

```

Tests execute automatically on CI.

## Complete Contribution Example

```bash

# Clone and install

git clone https://github.com/PrimeIntellect-ai/prime-agent.git
cd prime-agent
npm ci
cd prime-agent-runtime && pip install -e . && cd ..

# Create branch

git checkout -b fix-token-leak

# Edit files, then verify

npm run check

# Commit precisely

git add packages/ai/src/token-utils.ts
git commit -m "fix(ai): prevent token leakage in streaming response"

# Push when approved by maintainers

git push origin fix-token-leak

```

## Essential Files to Bookmark

- **[`CONTRIBUTING.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/CONTRIBUTING.md)** — Full contribution policy and PR preparation steps
- **[`README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md)** — High-level overview and command reference
- **[`packages/coding-agent/docs/development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md)** — Local development setup and testing guidelines
- **[`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts)** — LLM provider registry
- **[`src/daemon-schema.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/daemon-schema.ts)** — Daemon-worker protocol definition
- **[`packages/tui/src/render.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/render.ts)** — Core TUI rendering logic

## Summary

- **Start with a GitHub Discussion** — PRs require maintainer invitation
- **Respect the monorepo structure** — Target the correct `packages/` directory for your change
- **Run `npm run check`** — Type-checking is mandatory before commits
- **Commit precisely** — Never use `git add -A` or `--no-verify`
- **Include tests** — Every feature needs Vitest coverage in the appropriate package

## Frequently Asked Questions

### Can I open a pull request without starting a discussion first?

No. Prime Agent requires all potential contributors to begin with a GitHub Discussion. Maintainers convert discussions to Issues and invite vetted contributors to submit PRs. This policy ensures alignment with project goals before code is written.

### What Node.js and npm versions do I need?

The repository requires **npm version 11.10 or higher**. Run `npm ci` to install dependencies with the exact versions specified in lockfiles. The Python runtime requires a standard pip-installable environment for `prime-agent-runtime`.

### Where do I add a new LLM provider?

Add new providers in the `packages/ai` package. Define types in [`src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/types.ts), implement streaming in `src/providers/<provider>.ts`, register in [`src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/providers/register-builtins.ts), and configure credentials in [`src/env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/env-api-keys.ts). Follow the lazy-loading pattern used by existing providers.

### How do I test my changes locally?

Run `npm run check` for type-checking after every edit. For unit tests, use `npx vitest run <test-file>` targeting your package's test directory. The CI pipeline runs the same checks, so fix all errors before pushing.