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

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, packages/ai/README.md
packages/tui	Text-based UI rendering chat, keybindings, markdown	packages/tui/src/index.ts
packages/agent	High-level orchestration of agents and daemon communication	packages/agent/src/index.ts
packages/coding-agent	Main CLI, session management, dev utilities	packages/coding-agent/docs/development.md
prime-agent-runtime	Python runtime hosting the IPython kernel	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

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:

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.

3. Create a Focused Branch

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:

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:

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:

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

Adding new commands or events requires:

• Updating the protocol version
• Modifying compatibility maps

See the Daemon Protocol Changes section in AGENTS.md for specifications.

Streaming LLM Provider Abstraction

Providers register lazily in packages/ai/src/providers/register-builtins.ts. To add a new LLM provider:

1. Define option types in src/types.ts
2. Implement streaming functions in src/providers/<provider>.ts
3. Export the provider in src/index.ts
4. Update 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. 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:

npx vitest run <test-file>

Tests execute automatically on CI.

Complete Contribution Example

# 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 — Full contribution policy and PR preparation steps
• README.md — High-level overview and command reference
• packages/coding-agent/docs/development.md — Local development setup and testing guidelines
• packages/ai/src/providers/register-builtins.ts — LLM provider registry
• src/daemon-schema.ts — Daemon-worker protocol definition
• 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, implement streaming in src/providers/<provider>.ts, register in src/providers/register-builtins.ts, and configure credentials in 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.

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