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

> Debug PrimeAgent applications effectively. Learn to use environment variables like PI_DEBUG and PI_DEBUG_REDRAW, plus TUI diagnostics for detailed insights into your application's behavior.

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

---

**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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

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

```

Programmatically accessing the path:

```typescript
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/log.ts) to maintain consistent formatting and conditional output.

```typescript
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts).
- Use `PI_DEBUG_REDRAW=1` to trace every TUI render cycle in [`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts) for daemon-side failures.
- Import the `log` object from [`packages/ai/src/log.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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.