# PrimeAgent Logging Strategy: A Deep Dive into Console and File-Based Diagnostics

> Discover PrimeAgent's hybrid logging strategy. Learn how console logs and persistent debug files enhance development and TUI diagnostics for improved performance.

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

---

**PrimeAgent uses a hybrid logging approach that combines lightweight `console.log` output for development scripts with a persistent, per-user debug file (`~/.prime/agent/pi-debug.log`) for the interactive TUI and coding agent subsystems.**

The PrimeAgent repository implements a pragmatic logging strategy that distinguishes between transient developer feedback and durable runtime diagnostics. Rather than adopting a monolithic logging library, the codebase delegates output responsibilities based on execution context: ad-hoc scripts remain dependency-free while interactive components maintain a canonical debug trail.

## Hybrid Logging Architecture

PrimeAgent's logging design partitions responsibilities across two distinct channels. This separation keeps utility scripts portable while ensuring the interactive agent stack can be debugged retroactively.

### Console-Based Output for Scripts

All standalone utilities in the `scripts/` directory emit progress and diagnostic information directly to `stdout`. In files like [`scripts/tool-stats.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/tool-stats.ts), [`scripts/stats.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/stats.ts), and [`scripts/cost.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/cost.ts), the code uses native `console.log` calls without any abstraction layer.

This approach provides several advantages for developer tooling:

- **Zero dependencies** — scripts run without importing logging libraries
- **Unix composability** — output pipes naturally into `grep`, `jq`, or file redirects
- **Immediate visibility** — no log level configuration or file path management required

### File-Based Debug Logging for Interactive Components

The TUI and coding-agent subsystems write timestamped diagnostics to a shared debug file. The canonical location is constructed as:

```ts
// packages/tui/src/tui.ts
const logPath = path.join(os.homedir(), ".prime", "agent", "pi-debug.log");
const msg = `[${new Date().toISOString()}] ${reason}\n`;
fs.appendFileSync(logPath, msg);

```

The [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts) module centralizes this path construction through the `getDebugLogPath()` helper:

```ts
// packages/coding-agent/src/config.ts
export function getDebugLogPath(): string {
  return join(getAgentDir(), `${APP_NAME}-debug.log`);
}

```

This ensures both the TUI and coding-agent write to identical locations without hardcoding paths in multiple modules.

## Error-Aware Log Writing

When debug file operations fail, PrimeAgent surfaces errors to the user rather than swallowing exceptions. The interactive mode handler in [`packages/coding-agent/src/modes/interactive/interactive-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts) implements defensive writing:

```ts
// packages/coding-agent/src/modes/interactive/interactive-mode.ts
try {
  fs.appendFileSync(getDebugLogPath(), entry);
} catch (error) {
  this.showError(
    `Failed to write debug log: ${error instanceof Error ? error.message : String(error)}`
  );
}

```

The `showError()` method presents a user-visible notification, guaranteeing that permission denials, disk full conditions, or missing parent directories receive immediate attention.

## Log Management Characteristics

The PrimeAgent logging strategy deliberately omits automatic rotation. Key operational properties include:

- **No size-based rollover** — the debug file grows until manually pruned
- **Per-user isolation** — logs reside in `~/.prime/agent/`, avoiding repository pollution
- **CI-agnostic** — hidden directory placement prevents accidental VCS commits
- **Timestamped entries** — ISO 8601 prefixes enable chronological sorting and filtering

Users are expected to archive or truncate `pi-debug.log` when it reaches unwieldy sizes. This trade-off favors implementation simplicity over operational automation.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts) | Constructs debug path and appends TUI diagnostics |
| [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts) | Exports `getDebugLogPath()` for consistent log location |
| [`packages/coding-agent/src/modes/interactive/interactive-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts) | Handles write failures via `showError()` |
| [`scripts/tool-stats.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/tool-stats.ts), [`scripts/stats.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/stats.ts), [`scripts/cost.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/cost.ts) | Use `console.log` for script output |

## Summary

- **PrimeAgent logging is context-dependent**: `console.log` for scripts, file-based for interactive components
- **Debug logs concentrate at `~/.prime/agent/pi-debug.log`** via centralized path helpers
- **Write failures propagate to users** through `showError()` rather than silent drops
- **No automatic rotation** — manual maintenance required for long-running deployments
- **Zero external logging dependencies** — implementation uses only Node.js `fs` and `console` APIs

## Frequently Asked Questions

### Where does PrimeAgent store its debug logs?

PrimeAgent writes persistent debug logs to `~/.prime/agent/pi-debug.log` in the user's home directory. The TUI constructs this path using `path.join(os.homedir(), ".prime", "agent", "pi-debug.log")`, and the coding-agent module exposes the identical location through `getDebugLogPath()` in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts).

### Why doesn't PrimeAgent use a structured logging library?

The codebase prioritizes minimal dependencies and execution-context flexibility. Scripts in `scripts/` remain lightweight with native `console.log`, while interactive components need only append timestamped strings to a file. This avoids the configuration overhead and bundle size impact of libraries like `winston` or `pino`.

### How does PrimeAgent handle debug log write failures?

When `fs.appendFileSync` throws, the interactive mode catches the exception and invokes `this.showError()` with a descriptive message. This guarantees users receive immediate notification of permission problems or disk space exhaustion rather than losing diagnostic information silently.

### Is there automated log rotation in PrimeAgent?

No. The debug file grows without bound until manually archived or truncated. Users must periodically prune `~/.prime/agent/pi-debug.log` to prevent excessive disk consumption. The implementation favors simplicity over automated lifecycle management.