How to Debug PrimeAgent Applications: Environment Variables, Log Files, and TUI Diagnostics

To debug PrimeAgent applications, enable the PI_DEBUG environment variable to write structured logs to the path returned by getDebugLogPath(), set PI_DEBUG_REDRAW=1 to trace TUI render cycles, and press Shift+Ctrl+D inside the interface to dump the current UI state to /tmp/tui/.

PrimeAgent, the open-source AI coding agent from PrimeIntellect-ai/prime-agent, includes a comprehensive debugging subsystem to help developers trace execution flow and diagnose rendering issues. The architecture separates frontend TUI diagnostics from backend RPC instrumentation, allowing you to pinpoint failures in the terminal interface, the daemon process, or the communication layer between them. This guide explains how to activate these diagnostic features using the actual source implementation.

Enabling Debug Logging with Environment Variables

PrimeAgent uses three distinct environment flags to control diagnostic verbosity without recompiling the TypeScript source.

General Debug Output with PI_DEBUG

Setting PI_DEBUG=1 activates the unified logging system defined in packages/ai/src/log.ts. When enabled, calls to log.debug(), log.info(), and log.error() append timestamped, JSON-encoded entries to the debug log file returned by getDebugLogPath() in packages/coding-agent/src/config.ts. In production builds, these methods are no-ops unless the flag is present, ensuring zero runtime overhead during normal operation.

Tracing TUI Redraw Cycles with PI_DEBUG_REDRAW

Layout issues in the terminal interface can be diagnosed by exporting PI_DEBUG_REDRAW=1. This flag instructs the render loop in packages/tui/src/tui.ts to log every redraw cycle, including component dimensions and update timestamps. The output helps identify infinite re-render loops or inefficient layout calculations that cause flickering.

Capturing Render Passes with PI_DEBUG_RENDER

For pixel-perfect debugging, PI_DEBUG_RENDER=1 persists each TUI frame to a file under /tmp/tui/. These snapshots contain the exact character grid and styling attributes sent to the terminal, allowing post-mortem analysis of formatting errors or color code issues.

Locating and Reading Debug Log Files

The central debug log path is determined at runtime by the getDebugLogPath() function in packages/coding-agent/src/config.ts. By default, this resolves to ~/.prime/agent/prime-agent-debug.log, though the exact location varies by platform and user configuration.

To inspect logs in real-time:

tail -f ~/.prime/agent/prime-agent-debug.log

Programmatically accessing the path:

import { getDebugLogPath } from "@prime-agent/coding-agent/config";

const debugPath = getDebugLogPath();
console.log(`Debug log location: ${debugPath}`);

Interactive Debugging Using the Global Debug Key

When running the TUI, you can trigger an immediate state dump without restarting the application. Pressing Shift+Ctrl+D invokes the global debug handler implemented in packages/tui/src/tui.ts. This handler serializes the current component tree, pending events, and internal buffers to a timestamped file under /tmp/tui/render-<timestamp>.log. The shortcut is always active when PI_DEBUG is enabled, providing instant visibility into UI state during interactive sessions.

Debugging RPC and Daemon Processes

Backend communication issues are captured through dedicated instrumentation in the RPC client. The packages/coding-agent/src/modes/rpc/rpc-client.ts module collects the child process's stderr stream and exposes it via getCollectedStderr(), allowing you to inspect daemon crashes or protocol errors that never reach the TUI.

Additionally, the interactive mode in packages/coding-agent/src/modes/interactive/interactive-mode.ts implements a /debug command that forces a write of the current agent state to the debug log, bridging the gap between user commands and background processes.

Adding Custom Debug Statements

When extending PrimeAgent, use the centralized log object from packages/ai/src/log.ts to maintain consistent formatting and conditional output.

import { log } from "@prime-agent/ai";

export function processUserCommand(input: string) {
  log.debug("Processing command", { input, timestamp: Date.now() });
  
  // ... business logic ...
  
  log.info("Command completed successfully");
}

The abstraction automatically respects the PI_DEBUG flag, writing to the filesystem when enabled and silently returning when disabled.

Summary

• Export PI_DEBUG=1 to enable structured logging to the path returned by getDebugLogPath() in packages/coding-agent/src/config.ts.
• Use PI_DEBUG_REDRAW=1 to trace every TUI render cycle in packages/tui/src/tui.ts and diagnose layout thrashing.
• Press Shift+Ctrl+D inside the TUI to dump the current UI state to /tmp/tui/ for immediate inspection.
• Inspect RPC stderr via getCollectedStderr() in packages/coding-agent/src/modes/rpc/rpc-client.ts for daemon-side failures.
• Import the log object from packages/ai/src/log.ts to add conditional debug statements that respect the global debug configuration.

Frequently Asked Questions

Where does PrimeAgent store its debug logs?

By default, PrimeAgent writes debug logs to ~/.prime/agent/prime-agent-debug.log, as defined by the getDebugLogPath() function in packages/coding-agent/src/config.ts. The exact path is resolved at runtime based on the user's home directory and platform conventions.

How do I enable debug mode without editing the source code?

Set the PI_DEBUG=1 environment variable before launching the application. For TUI-specific issues, additionally export PI_DEBUG_REDRAW=1 or PI_DEBUG_RENDER=1 to capture render cycles and frame snapshots without modifying any TypeScript files.

What is the keyboard shortcut to dump TUI state at runtime?

Press Shift+Ctrl+D while the TUI is focused. This triggers the debug handler in packages/tui/src/tui.ts to write a serialized snapshot of the current UI state to /tmp/tui/render-<timestamp>.log, which you can inspect with any text editor.

How can I capture stderr from the PrimeAgent daemon?

The RPC client in packages/coding-agent/src/modes/rpc/rpc-client.ts automatically collects stderr from the child process. Access this buffer programmatically by calling getCollectedStderr() to view startup errors or protocol mismatches that occur before the logging subsystem initializes.

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