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

The utils package in PrimeAgent delivers specialized, pure utility functions across three distinct modules—terminal UI handling in packages/tui/src/utils.ts, LLM message compaction in packages/coding-agent/src/core/compaction/utils.ts, and plan-mode formatting in 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, 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 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

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

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

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, packages/coding-agent/src/core/compaction/utils.ts, and 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 for terminal UI operations, packages/coding-agent/src/core/compaction/utils.ts for LLM message management, and 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. 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 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. 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.

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