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

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
• Unified build: The root npm run check script compiles every package using its respective 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

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

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

{
  "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

Extend the base configuration and specify output settings:

{
  "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, expose only the symbols you want public:

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:

npm run check

The root 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:

mv packages/ai libs/ai

2. Update the workspace glob in package.json (root):

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

3. Verify 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. 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. Add custom steps for your new packages:

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

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

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

Update package.json Exports

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

{
  "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 (root)	Workspace declaration, shared scripts	Adding new top-level directories to workspaces
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	Version bumping across packages	Ensuring new packages are included in releases
.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 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 and CI workflows to include your changes in the release pipeline
• Expand public APIs by adding exports to src/index.ts and updating the exports field in 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, 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 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 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, 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. The monorepo tooling links these automatically during npm install. The TypeScript path aliases in tsconfig.base.json enable IDE support and proper resolution during builds.

What happens if I forget to add a package to 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.

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