# How the Utils Package Provides Utility Functions for PrimeAgent: Core Helpers Explained

> Discover how the PrimeAgent utils package offers essential utility functions for terminal UI, LLM message compaction, and plan-mode formatting. Explore the core helpers explained.

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

---

**The utils package in PrimeAgent delivers specialized, pure utility functions across three distinct modules—terminal UI handling in [`packages/tui/src/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/utils.ts), LLM message compaction in [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/compaction/utils.ts), and plan-mode formatting in [`packages/coding-agent/examples/extensions/plan-mode/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/examples/extensions/plan-mode/utils.ts)—enabling consistent ANSI text wrapping, token-aware payload truncation, and structured plan presentation throughout the PrimeIntellect-ai/prime-agent codebase.**

The PrimeAgent repository by PrimeIntellect-ai organizes shared functionality into focused utility modules that prevent code duplication across the TUI renderer, coding agent core, and extension examples. These **utils package utility functions** handle everything from ANSI escape sequence management to token budget enforcement, providing pure, side-effect-free helpers that maintain consistency across the entire system.

## Core Utility Modules in PrimeAgent

### Terminal UI Helpers in packages/tui/src/utils.ts

The TUI package contains utilities for handling ANSI-colored strings and terminal measurements. The `wrapAnsi` function parses ANSI escape sequences to measure visible cell width while preserving color codes during line wrapping. This ensures that colored terminal output respects column constraints without breaking escape sequences or miscounting Unicode character widths.

### Message Compaction Utilities in packages/coding-agent/src/core/compaction/utils.ts

The coding agent's compaction module provides `estimateTokens` and `truncateMessage` functions to enforce LLM provider token limits. These utilities calculate token consumption using the same tokenizer as the target provider, then truncate oversized payloads by merging adjacent text nodes or removing content while preserving message structure. This prevents request failures when conversation histories grow beyond context windows.

### Plan-Mode Extension Helpers in packages/coding-agent/examples/extensions/plan-mode/utils.ts

The plan-mode extension demonstrates how to build domain-specific utilities with `formatPlanStep`, which converts plan step objects into emoji-enhanced display strings. This helper constructs concise human-readable representations of planning stages, enabling quick user feedback in terminal interfaces without cluttering the core agent logic.

## Architectural Design Patterns

### Isolation of Pure Functions

Each utility module contains **pure functions** that operate exclusively on input parameters without side effects. In [`packages/tui/src/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/utils.ts), string manipulation functions process raw text and return transformed output without interacting with the terminal directly. Similarly, [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/compaction/utils.ts) performs calculations on message objects without modifying global state, ensuring predictable behavior across the application.

### Cross-Package Reusability

Because these utilities carry minimal dependencies, they import cleanly across package boundaries. The ANSI wrapping logic serves any component rendering multiline terminal text, while compaction helpers integrate with multiple LLM stream providers to respect token limits consistently. This reuse prevents the proliferation of duplicate string-processing implementations while maintaining uniform behavior.

## Practical Implementation Examples

### Wrapping ANSI-Colored Text

```typescript
import { wrapAnsi } from '@prime-agent/tui/src/utils';

// Handle colored strings that must fit within 80 columns
const coloured = '\x1b[31mThis is a very long red message requiring wrapping.\x1b[0m';
const wrapped = wrapAnsi(coloured, 80);
console.log(wrapped);

```

The `wrapAnsi` function calculates visible width by parsing escape sequences, ensuring line breaks insert only at appropriate character boundaries without corrupting color codes.

### Enforcing Token Budgets

```typescript
import { truncateMessage, estimateTokens } from '@prime-agent/coding-agent/src/core/compaction/utils';

const largeMessage = { role: 'assistant', content: '…very long text…' };
const maxTokens = 1024;

if (estimateTokens(largeMessage) > maxTokens) {
  const compacted = truncateMessage(largeMessage, maxTokens);
  // Send compacted payload to avoid provider errors
}

```

This pattern guarantees outbound requests stay within provider limits by estimating usage before transmission and intelligently truncating content.

### Formatting Plan Steps

```typescript
import { formatPlanStep } from '@prime-agent/coding-agent/examples/extensions/plan-mode/utils';

const step = { index: 1, title: 'Refactor module', description: 'Split large file' };
console.log(formatPlanStep(step));
// Output: "1️⃣ Refactor module – Split large file"

```

## Summary

- The **utils package** distributes specialized helpers across three specific file locations: [`packages/tui/src/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/utils.ts), [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/compaction/utils.ts), and [`packages/coding-agent/examples/extensions/plan-mode/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/examples/extensions/plan-mode/utils.ts).
- **Terminal utilities** handle ANSI escape sequences and line wrapping without breaking color codes or miscounting cell widths.
- **Compaction functions** estimate token usage and truncate messages to respect LLM provider context limits while merging adjacent text nodes.
- **Extension utilities** demonstrate domain-specific formatting for plan-mode workflows, keeping core agent logic uncluttered.
- All utility modules follow **pure function principles**, enabling safe cross-package imports and comprehensive unit testing.

## Frequently Asked Questions

### Where are the main utility functions located in PrimeAgent?

The primary utility functions reside in three specific paths within the PrimeIntellect-ai/prime-agent repository: [`packages/tui/src/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/utils.ts) for terminal UI operations, [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/compaction/utils.ts) for LLM message management, and [`packages/coding-agent/examples/extensions/plan-mode/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/examples/extensions/plan-mode/utils.ts) for plan formatting examples. Each module serves distinct architectural layers while maintaining zero external side effects.

### How does PrimeAgent handle ANSI text formatting in the terminal?

PrimeAgent processes ANSI-colored text through the `wrapAnsi` function exported from [`packages/tui/src/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/utils.ts). This utility parses escape sequences to measure visible character width accurately, then inserts line breaks at appropriate boundaries while preserving color codes and handling Unicode surrogate pairs correctly.

### What is the purpose of message compaction utilities in the coding agent?

The compaction utilities in [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/compaction/utils.ts) provide `estimateTokens` and `truncateMessage` functions that calculate token consumption using provider-specific tokenizers and reduce payload size when conversations exceed context windows. These helpers merge adjacent text nodes and remove excess content while preserving the semantic structure required for LLM interactions.

### Can developers create custom utility modules for PrimeAgent extensions?

Yes, developers can create domain-specific utility files following the pattern established in [`packages/coding-agent/examples/extensions/plan-mode/utils.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/examples/extensions/plan-mode/utils.ts). By implementing pure functions that accept simple data structures and return transformed output, extension authors maintain compatibility with PrimeAgent's architectural standards while adding specialized formatting or data manipulation capabilities.