# Logging Package in PrimeAgent: Structured Observability for AI Agents

> Explore the PrimeAgent logging package for structured observability. Centralize runtime diagnostics in JSON-Lines files for deep insights into agent behavior.

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

---

**The logging package in PrimeAgent centralizes runtime diagnostics through a JSON-Lines file sink that captures structured events from the agent core and integrated libraries at `~/.prime/agent/logs/agent.jsonl`.**

PrimeAgent, developed by PrimeIntellect-ai, implements a unified observability layer through its dedicated logging module. This system ensures that every component—from the interactive client to the background daemon—emits structured, context-rich diagnostics to a single, rotating log file.

## Core Logging Architecture

### The Central Module in logging.ts

The logging package lives in [`packages/coding-agent/src/core/logging.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/logging.ts) and exposes two primary public helpers that handle all runtime diagnostics. This module acts as the single integration point for both internal PrimeAgent components and the underlying **@earendil-works/pi-ai** library.

The module provides:

- **`installFileLogSink([fields])`** – Installs a global log sink that writes every structured log entry to a single JSON-Lines file
- **`setLogContext(fields)`** – Merges additional context (such as *mode* or *sessionId*) into the log entry `context` object for all subsequent writes

### Configuration and Path Resolution

Log file paths are resolved by `getAgentLogPath()` in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts), which targets the user’s home directory at `~/.prime/agent/logs/`. This configuration module also implements the `appendRotatingLog` utility that guarantees writes never throw exceptions, even when encountering read-only directories.

## File Management and Rotation Strategy

### Automatic Size-Bounded Rotation

The logging package implements a single-generation rotation strategy via `appendRotatingLog` in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts). When the log file reaches approximately **20 MiB**, the system automatically drops the oldest generation to prevent unbounded disk growth.

This rotation mechanism ensures that the JSON-Lines file at `~/.prime/agent/logs/agent.jsonl` remains manageable while preserving recent diagnostic history. If the log directory becomes read-only, the sink silently handles the error without crashing the agent process.

### Path Resolution Implementation

The `getAgentLogPath()` function constructs the canonical log location under the user’s home directory. This centralized path management ensures that both the daemon and client processes write to the same physical file, enabling unified debugging across process boundaries.

## Runtime Integration and Bootstrap

### Startup Sequence in main.ts

PrimeAgent installs the logging sink early in its startup sequence to capture all initialization events. In [`packages/coding-agent/src/main.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/main.ts), the bootstrap code imports and invokes the logging helpers before any other subsystem initializes:

```ts
// src/main.ts – bootstrap logging for every run
import { installFileLogSink, setLogContext } from "./core/logging.js";

installFileLogSink();               // Create the JSONL sink at ~/.prime/agent/logs/agent.jsonl
setLogContext({ mode: "interactive" }); // Add runtime mode to all subsequent entries

```

This early installation ensures that **all** components—including the daemon, client, and provider diagnostics—share the same structured log output.

### External Library Integration

The logging package integrates with the **@earendil-works/pi-ai** library to capture its structured diagnostics in the same JSON-Lines stream. This integration happens transparently through the global sink installed by `installFileLogSink()`, allowing PrimeAgent to monitor AI provider interactions alongside native agent events:

```ts
// Example of emitting a structured log (from @earendil‑works/pi‑ai)
import { log } from "@earendil-works/pi-ai";

log.info({ event: "tool_call", tool: "search", query: "prime agent logging" });

```

## Context Enrichment with setLogContext

The `setLogContext` function enables dynamic augmentation of log entries with runtime metadata. After calling this function, every subsequent log line automatically includes the specified fields in its context object:

```ts
// In any module that needs extra context
import { setLogContext } from "./core/logging.js";

setLogContext({ sessionId: "abcd1234" });

```

This capability supports **unified observability** by injecting persistent identifiers such as PID, session ID, or execution mode into every log record without requiring manual passing of context objects through the call stack.

## Summary

- The **logging package in PrimeAgent** centralizes diagnostics through [`packages/coding-agent/src/core/logging.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/logging.ts), providing `installFileLogSink()` and `setLogContext()` as the primary public API.
- Log files are written to `~/.prime/agent/logs/agent.jsonl` as JSON-Lines, with paths resolved by `getAgentLogPath()` in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts).
- The `appendRotatingLog` utility enforces a **~20 MiB size limit** through single-generation rotation that silently drops old entries when bounds are exceeded.
- **Bootstrap initialization** occurs in [`packages/coding-agent/src/main.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/main.ts), ensuring the sink captures events from the daemon, client, and **@earendil-works/pi-ai** library from startup.

## Frequently Asked Questions

### Where does PrimeAgent store its log files?

PrimeAgent writes structured logs to `~/.prime/agent/logs/agent.jsonl`, a JSON-Lines file located in the user’s home directory. The `getAgentLogPath()` function in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts) resolves this canonical path to ensure both client and daemon processes write to the same location.

### How does PrimeAgent prevent log files from consuming too much disk space?

The logging package implements size-bounded storage through the `appendRotatingLog` utility in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts). When the log file approaches **20 MiB**, the system automatically drops the oldest generation to maintain the size limit, ensuring logs never grow unbounded even during extended runtime.

### Can I add custom context to PrimeAgent logs?

Yes. The `setLogContext(fields)` function in [`packages/coding-agent/src/core/logging.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/logging.ts) merges custom fields into the context object for all subsequent log entries. This allows injection of session IDs, execution modes, or other metadata that persists across asynchronous operations without manual context threading.

### How does PrimeAgent capture logs from external libraries?

PrimeAgent captures diagnostics from **@earendil-works/pi-ai** by installing a global file sink via `installFileLogSink()` during bootstrap. This sink intercepts structured log events from the external library and writes them to the same JSON-Lines file as native agent events, creating a unified observability stream for debugging AI provider interactions.