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

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

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:

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

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

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 to drive a headless terminal and assert the final viewport state without launching an actual UI.

Daemon protocol compatibility:

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.

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

The suite harness (test/suite/harness.ts) launches the faux provider and exercises scenarios such as agent-connection-daemon.test.ts (verifying DaemonAgentConnection reconstruction) and interactive-mode-boundary.test.ts (ensuring sessions survive daemon restarts). As documented in 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 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), TUI rendering (packages/tui/test/terminal.test.ts), or daemon protocols (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. This provider simulates AI responses deterministically, allowing you to run 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. 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 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.

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