# How to Test Changes to PrimeAgent: A Complete Guide for the Monorepo

> Easily test your PrimeAgent changes in the monorepo. Run npm run check and use Vitest for package or full suite testing across AI TUI and agent layers.

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

---

**Run `npm run check` from the repository root to validate formatting, types, and linting, then execute focused package tests or the high-level suite using Vitest to ensure your changes work across the AI, TUI, and agent layers.**

PrimeAgent is a multi-package TypeScript monorepo maintained by PrimeIntellect-ai. Whether you are modifying the AI streaming logic in `packages/ai`, the terminal interface in `packages/tui`, or the daemon protocol in `packages/agent`, you need a systematic way to test changes to PrimeAgent without breaking the integrated runtime. The repository enforces a three-layer validation strategy that moves from static analysis to deterministic end-to-end simulation.

## The Three-Layer Testing Strategy

PrimeAgent organizes validation into distinct layers to catch errors early and avoid expensive real API calls during testing.

### Static Validation with npm run check

The first line of defense is the repository-wide static check. Executing `npm run check` from the root runs Prettier, ESLint, `tsc --noEmit`, installer rendering validation, and a browser-smoke check. This command ensures the codebase remains type-safe and correctly formatted before any test logic executes. According to the contribution guidelines in [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md), this step must always pass before you commit changes.

### Package-Level Unit and Integration Tests

Each package maintains its own test directory for focused validation. These tests use Vitest and cover provider-agnostic AI logic, TUI rendering, and daemon protocol compatibility. You run these from within the specific package directory to get rapid feedback on isolated components.

### High-Level Suite Tests with the Faux Provider

The `packages/coding-agent/test/suite/` directory contains deterministic end-to-end tests that exercise `AgentSession` and `AgentSessionRuntime`. These tests use the `faux` provider implementation in [`packages/ai/src/providers/faux.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/faux.ts) to simulate AI responses without requiring real API keys, making them safe for CI and local development.

## Step-by-Step Testing Workflow

Follow this sequence after modifying any source file to ensure comprehensive coverage.

### 1. Validate Static Requirements

Always start with the static validation to catch type errors and formatting issues immediately.

```bash
npm run check

```

This command validates the entire monorepo. If it reports errors, fix them before proceeding to functional tests.

### 2. Run Targeted Package Tests

Navigate to the package you modified and execute the relevant test file using Vitest via `tsx`.

**AI streaming and tool-call logic:**

```bash
cd packages/ai
npx tsx ../../node_modules/vitest/dist/cli.js --run test/stream.test.ts

```

The [`stream.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/stream.test.ts) file validates the core `stream()` and `complete()` functions, including tool-call handling and text-generation events. Examine this file to understand how the AI layer asserts streaming behavior.

**TUI rendering and keyboard handling:**

```bash
cd packages/tui
npx tsx ../../node_modules/vitest/dist/cli.js --run test/terminal.test.ts

```

These tests leverage the `VirtualTerminal` helper exported from [`packages/tui/src/terminal.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/terminal.ts) to drive a headless terminal and assert the final viewport state without launching an actual UI.

**Daemon protocol compatibility:**

```bash
cd packages/agent
npx tsx ../../node_modules/vitest/dist/cli.js --run test/daemon-protocol.test.ts

```

This suite covers command/event compatibility maps and version-negotiation logic between the agent and its daemon.

### 3. Execute End-to-End Suite Tests

Run the high-level integration tests to verify that your changes work within the full agent runtime.

```bash
cd packages/coding-agent
npx tsx ../../node_modules/vitest/dist/cli.js --run test/suite/**/*.test.ts

```

The suite harness ([`test/suite/harness.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/test/suite/harness.ts)) launches the `faux` provider and exercises scenarios such as [`agent-connection-daemon.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-connection-daemon.test.ts) (verifying `DaemonAgentConnection` reconstruction) and [`interactive-mode-boundary.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/interactive-mode-boundary.test.ts) (ensuring sessions survive daemon restarts). As documented in [`packages/coding-agent/test/suite/README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/suite/README.md), these tests are strictly deterministic because they never hit real provider endpoints.

## Debugging Test Failures

When a test fails, PrimeAgent provides specific tooling to diagnose issues. The repository includes a hidden `/debug` command that writes detailed execution logs to `~/.prime/agent/prime-agent-debug.log`, which is particularly useful for diagnosing TUI failures. For rendering synchronization issues, use the `VirtualTerminal.waitForRender()` helper found in [`packages/tui/src/terminal.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/terminal.ts) to align assertions with the throttled render pipeline.

**Typical debugging workflow:**

1. Re-run the failing test with `DEBUG=1` (or the package-specific environment variable).
2. Inspect the generated log file at `~/.prime/agent/prime-agent-debug.log`.
3. Fix the source code, then repeat `npm run check` and the specific test until it passes.

## Continuous Integration Requirements

The CI pipeline mirrors the local workflow exactly: it executes `npm run check` followed by the full suite test command. Note that `npm test` is disabled by policy in this repository. When contributing new tests, place end-to-end scenarios under `packages/coding-agent/test/suite/` and unit tests under the appropriate package’s `test/` directory. Never commit real provider API keys; the `faux` provider implementation ensures all suite tests remain infrastructure-independent.

## Summary

- **Start with `npm run check`** from the repository root to enforce types, linting, and formatting across the monorepo.
- **Use package-level tests** for rapid iteration on specific components like AI streaming ([`packages/ai/test/stream.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/test/stream.test.ts)), TUI rendering ([`packages/tui/test/terminal.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/test/terminal.test.ts)), or daemon protocols ([`packages/agent/test/daemon-protocol.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/test/daemon-protocol.test.ts)).
- **Run the suite tests** in `packages/coding-agent/test/suite/` to validate full runtime behavior using the deterministic `faux` provider.
- **Leverage `/debug` and `VirtualTerminal.waitForRender()`** when troubleshooting failures in complex integration scenarios.

## Frequently Asked Questions

### What is the fastest way to test a small change in PrimeAgent?

Execute `npm run check` from the root to catch static errors, then navigate to the specific package you modified (e.g., `cd packages/ai`) and run the relevant Vitest file directly (e.g., `npx tsx ../../node_modules/vitest/dist/cli.js --run test/stream.test.ts`). This targeted approach avoids running the entire monorepo test suite while validating your specific modification.

### Do I need API keys to run the test suite?

No. The high-level suite tests in `packages/coding-agent/test/suite/` use the `faux` provider implementation located at [`packages/ai/src/providers/faux.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/faux.ts). This provider simulates AI responses deterministically, allowing you to run [`agent-connection-daemon.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-connection-daemon.test.ts) and other integration tests without configuring real API credentials or incurring costs.

### Which test file should I examine to understand AI streaming tests?

Refer to [`packages/ai/test/stream.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/test/stream.test.ts). This file demonstrates how to validate the `stream()` and `complete()` functions, including assertions for tool-call handling and text-generation events. It serves as the canonical example for testing provider-agnostic AI logic in the monorepo.

### How do I debug TUI rendering issues in tests?

Use the `VirtualTerminal` helper from [`packages/tui/src/terminal.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/terminal.ts) to drive headless terminal interactions. If a test fails, trigger the hidden `/debug` command to generate a detailed log at `~/.prime/agent/prime-agent-debug.log`, and utilize `VirtualTerminal.waitForRender()` to synchronize your test assertions with the rendering pipeline’s timing.