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

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, scripts/stats.ts, and 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:

// 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 module centralizes this path construction through the getDebugLogPath() helper:

// 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 implements defensive writing:

// 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	Constructs debug path and appends TUI diagnostics
packages/coding-agent/src/config.ts	Exports getDebugLogPath() for consistent log location
packages/coding-agent/src/modes/interactive/interactive-mode.ts	Handles write failures via showError()
scripts/tool-stats.ts, scripts/stats.ts, 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.

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.

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