# How to Customize the Package Structure of PrimeAgent: A Complete Guide

> Customize PrimeAgent's package structure using its monorepo architecture npm workspaces and TypeScript. This guide explains how to tailor PrimeAgent to your specific needs.

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

---

**Yes, you can fully customize the package structure of PrimeAgent by leveraging its monorepo architecture built on npm workspaces and TypeScript project references.**

PrimeAgent is organized as a **monorepo** that groups its core functionality into distinct packages under the `packages/` directory. Each package operates as a self-contained TypeScript/Node module with its own build configuration, dependencies, and public API exports. This architecture makes it straightforward to add, remove, or reorganize packages while maintaining a cohesive build and release process.

## Understanding PrimeAgent's Monorepo Architecture

The repository follows a standard npm workspace pattern with lock-step versioning across all packages.

```

prime-agent/
├─ package.json               ← Root npm configuration with workspaces
├─ tsconfig.base.json        ← Base TypeScript settings shared across packages
├─ packages/
│   ├─ ai/                    ← LLM provider abstractions
│   ├─ agent/                ← Core agent runtime
│   ├─ coding-agent/         ← CLI, skill system, and daemon logic
│   └─ tui/                  ← Terminal UI front-end
└─ scripts/                  ← Build, release, and utility scripts

```

Key architectural principles from the PrimeAgent source code:

- **Lock-step releases**: All packages share the same version number, synchronized by [`scripts/sync-versions.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/sync-versions.js)
- **Unified build**: The root `npm run check` script compiles every package using its respective [`tsconfig.build.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tsconfig.build.json)
- **Package-level entry points**: Public APIs are exported from `packages/*/src/index.ts` and exposed via `"exports"` fields in `packages/*/package.json`

## Method 1: Add a New Package to PrimeAgent

Creating a new package requires four files and minimal configuration changes.

### Step 1: Create the Directory Structure

```bash
mkdir -p packages/utils/src
touch packages/utils/src/index.ts
touch packages/utils/tsconfig.build.json
touch packages/utils/package.json

```

### Step 2: Configure [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json)

The package name must follow the `@prime-agent/` namespace convention. Define the export map to control how consumers import your code:

```json
{
  "name": "@prime-agent/utils",
  "version": "0.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "scripts": {
    "build": "tsc -p tsconfig.build.json"
  }
}

```

### Step 3: Configure [`tsconfig.build.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tsconfig.build.json)

Extend the base configuration and specify output settings:

```json
{
  "extends": "../../tsconfig.base.json",
  "include": ["src/**/*.ts"],
  "compilerOptions": {
    "outDir": "dist",
    "declaration": true,
    "sourceMap": true
  }
}

```

### Step 4: Export Your Public API

In [`packages/utils/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/utils/src/index.ts), expose only the symbols you want public:

```typescript
export function camelToSnake(str: string): string {
  return str.replace(/[A-Z]/g, letter => '_' + letter.toLowerCase());
}

```

### Step 5: Verify the Build

Run the repository-wide check command to compile your new package:

```bash
npm run check

```

The root [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) already includes `"workspaces": ["packages/*"]`, so your new folder is automatically recognized.

## Method 2: Rearrange Existing Packages

You can relocate packages without breaking internal imports, thanks to the namespace-based import pattern.

### Move a Package to a Different Location

For example, moving `packages/ai/` to `libs/ai/`:

1. **Move the folder**:

```bash
mv packages/ai libs/ai

```

2. **Update the workspace glob** in [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) (root):

```json
{
  "workspaces": ["packages/*", "libs/*"]
}

```

3. **Verify [`tsconfig.base.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tsconfig.base.json) paths**: The existing `@prime-agent/*` path mappings typically cover all workspace locations, but confirm your new path is included.

4. **Internal imports remain unchanged**: Code using `import { ... } from '@prime-agent/ai'` continues to work because the package name, not the filesystem path, drives module resolution.

## Method 3: Customize Build Order and Inter-Package Scripts

PrimeAgent's build orchestration lives in several key files you can modify.

### Update Version Synchronization

When adding a package, ensure it's included in the lock-step release process by examining [`scripts/sync-versions.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/sync-versions.js). This script iterates over all packages and bumps their versions simultaneously.

### Modify CI Pipeline Behavior

The build pipeline is defined in [`.github/workflows/ci.yml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/.github/workflows/ci.yml). Add custom steps for your new packages:

```yaml

# .github/workflows/ci.yml – add targeted linting for new packages

jobs:
  lint-utils:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Lint utils
        run: npx eslint packages/utils/src/**/*.ts

```

## Method 4: Expose New Public APIs

Expanding a package's surface area requires updates to both source and configuration files.

### Add Exports to Source

In `packages/<pkg>/src/index.ts`, add your new symbols:

```typescript
// Existing exports
export { AgentRuntime } from './runtime';

// New exports
export { createLogger, type LogLevel } from './logging';

```

### Update [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) Exports

For complex export patterns, modify the `exports` field to expose sub-paths:

```json
{
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./logging": {
      "import": "./dist/logging/index.js",
      "types": "./dist/logging/index.d.ts"
    }
  }
}

```

This enables consumers to use `import { createLogger } from '@prime-agent/agent/logging'`.

## Key Configuration Files for Package Structure Customization

| File | Purpose | When to Modify |
|------|---------|--------------|
| [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) (root) | Workspace declaration, shared scripts | Adding new top-level directories to workspaces |
| [`tsconfig.base.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tsconfig.base.json) | Path aliases, compiler defaults | Custom path mappings or global TS options |
| `packages/*/tsconfig.build.json` | Package-specific build settings | Per-package compiler flags or output locations |
| `packages/*/package.json` | Package metadata, export maps | Adding exports, changing entry points, dependencies |
| [`scripts/sync-versions.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/sync-versions.js) | Version bumping across packages | Ensuring new packages are included in releases |
| [`.github/workflows/ci.yml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/.github/workflows/ci.yml) | Continuous integration steps | Custom build, test, or lint steps for packages |

## Summary

Customizing the PrimeAgent package structure involves four core actions:

- **Create new packages** by adding folders under `packages/` (or your custom location) with standard npm layout and [`tsconfig.build.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tsconfig.build.json) extending the base config
- **Reorganize existing packages** by moving folders and updating workspace globs, with internal imports remaining stable due to namespace-based resolution
- **Adjust build orchestration** by modifying [`scripts/sync-versions.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/sync-versions.js) and CI workflows to include your changes in the release pipeline
- **Expand public APIs** by adding exports to [`src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/index.ts) and updating the `exports` field in [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json)

All changes are confined to configuration files—no source code modifications are required to reshape the monorepo layout.

## Frequently Asked Questions

### Can I rename an existing PrimeAgent package?

Yes. Rename the folder, update the `"name"` field in its [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json), then run a global find-and-replace across the repository for the old package name in `import` statements and dependency declarations. Update [`tsconfig.base.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tsconfig.base.json) path mappings if you referenced the old name directly.

### Do all packages need to be under `packages/`?

No. The workspace glob in root [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) controls which directories are included. You can add additional patterns like `"libs/*"` or `"tools/*"` and place packages there. Ensure each location follows the same structural conventions (`src/`, [`tsconfig.build.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tsconfig.build.json), [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json)).

### How does PrimeAgent handle cross-package dependencies?

Packages declare dependencies on other workspace packages using their npm names (e.g., `"@prime-agent/ai": "0.0.0"`) in their [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json). The monorepo tooling links these automatically during `npm install`. The TypeScript path aliases in [`tsconfig.base.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tsconfig.base.json) enable IDE support and proper resolution during builds.

### What happens if I forget to add a package to [`sync-versions.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/sync-versions.js)?

The version synchronization script may skip your package during releases, causing version drift. While the glob patterns in workspace configuration automatically discover packages for installation and building, explicit inclusion in release scripts ensures consistent versioning. Verify your package appears in the iteration logic within [`scripts/sync-versions.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/sync-versions.js).