# How to Debug Issues in PrimeAgent: Complete Troubleshooting Guide

> Debug PrimeAgent issues effectively. Use the doctor command, inspect logs, and apply automatic fixes with our complete troubleshooting guide for PrimeIntellect-ai/prime-agent.

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

---

**Use the `prime-agent doctor` command to diagnose component health, inspect logs in `~/.prime/agent/`, and apply automatic fixes with `--fix`.**

PrimeAgent is a multi-process AI coding system built by PrimeIntellect-ai that runs a **daemon**, **worker**, **kernel** (IPython REPL), and **TUI** frontend. When something breaks, you need targeted tools to inspect each layer. This guide walks through the exact debugging commands, log locations, and source code paths you need to resolve issues fast.

## The PrimeAgent Doctor Command

The `doctor` subcommand is your first diagnostic stop. It inspects the daemon, background services, and log files, then reports problems in human-readable or JSON format.

### Where the Doctor Lives in Source Code

The doctor implementation spans three files in `packages/coding-agent/src/cli/`:

| Component | Function | Source Location |
|-----------|----------|---------------|
| CLI dispatcher | Parses `doctor` arguments and calls `runDoctor()` | [`public-command.ts#L27-L46`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/public-command.ts#L27-L46) |
| Doctor logic | Runs health checks and optional repairs | [[`daemon-command.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-command.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/daemon-command.ts) |
| Process status | Lists active agents via `runPs()` | [[`daemon-ps.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-ps.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/daemon-ps.ts) |

### Basic Doctor Usage

```bash

# Human-readable health report

prime-agent doctor

# Machine-readable JSON output for scripting

prime-agent doctor --json

# Attempt automatic repairs

prime-agent doctor --fix --json

```

The `--fix` flag triggers cleanup of stale sockets, orphaned workers, and daemon restart if needed. This logic consumes the boolean flag parsed at [`public-command.ts#L63-L71`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/public-command.ts#L63-L71).

## Log File Locations

PrimeAgent writes two diagnostic log files to `~/.prime/agent/`:

| Log file | Purpose | Source reference |
|----------|---------|----------------|
| `pi-debug.log` | Per-render TUI diagnostics and error conditions | [`tui/src/tui.ts#L1671-L1680`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts#L1671-L1680) |
| `pi-crash.log` | Fatal crash stack traces | [`tui/src/tui.ts#L1855-L1860`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts#L1855-L1860) |

### Reading the Debug Log

```bash

# Last 40 lines of UI diagnostics

tail -n 40 ~/.prime/agent/pi-debug.log

# Follow live debug output

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

```

### Inspecting Crash Logs

```bash

# Full crash report with stack trace

cat ~/.prime/agent/pi-crash.log

```

## Complete Debugging Workflow

Follow these steps in order to isolate and resolve PrimeAgent issues.

### 1. Run Initial Health Check

```bash
prime-agent doctor --json | jq .

```

This returns JSON with daemon status, socket health, and any reclaimed processes. Look for keys like `reaped`, `skipped`, or `daemonHealthy`.

### 2. Check Running Agent Status

```bash
prime-agent status

```

This prints a table of active agents, their PIDs, and socket paths. It reuses the same `runPs()` helper as the doctor command.

### 3. Apply Automatic Repairs

If the doctor reports stale sockets or dead workers:

```bash
prime-agent doctor --fix --json

```

The repair routine in [[`daemon-command.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-command.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/daemon-command.ts) runs `runReap()` to clean up and attempts daemon restart if unresponsive.

### 4. Inspect Logs for Root Cause

```bash

# UI rendering issues

tail -n 50 ~/.prime/agent/pi-debug.log

# Fatal crashes

cat ~/.prime/agent/pi-crash.log

```

### 5. Re-attach or Resume Sessions

If the daemon is healthy but your session disappeared:

```bash

# Re-attach to specific agent

prime-agent attach <agent-id>

# Resume latest saved session after crash

prime-agent --resume

```

### 6. Force Clean Restart

When the daemon is completely unresponsive:

```bash

# Kill all agents and clean up

prime-agent shutdown --force

# Re-verify and repair

prime-agent doctor --fix

```

## Advanced Debugging: Common Scenarios

### Daemon Won't Start

```bash

# Check for stale socket files

prime-agent doctor

# Force cleanup and restart

prime-agent shutdown --force
prime-agent doctor --fix

```

### UI Freezes or Renders Incorrectly

```bash

# Check TUI render diagnostics

tail -n 100 ~/.prime/agent/pi-debug.log

# Look for repeated render loops or errors

grep -E "(render|error|timeout)" ~/.prime/agent/pi-debug.log | tail -20

```

### Kernel Crashes or IPython REPL Dies

```bash

# Re-attach attempts kernel reconnection

prime-agent attach <agent-id>

# Or resume full session state

prime-agent --resume

```

## Scripting Diagnostic Checks

Automate health monitoring in CI or systemd units:

```bash
#!/bin/bash

# exit-nonzero-on-unhealthy.sh

STATUS=$(prime-agent doctor --json)
HEALTHY=$(echo "$STATUS" | jq -r '.daemonHealthy')

if [ "$HEALTHY" != "true" ]; then
    echo "PrimeAgent unhealthy: $STATUS"
    prime-agent doctor --fix
    exit 1
fi

```

## Summary

- **Start with `prime-agent doctor`** — the unified diagnostic entry point implemented in [[`public-command.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/public-command.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/public-command.ts)
- **Use `--fix`** to automatically reap dead workers, delete stale sockets, and restart the daemon
- **Check `~/.prime/agent/pi-debug.log`** for TUI rendering issues and [[`tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tui/src/tui.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts) for log implementation details
- **Read `~/.prime/agent/pi-crash.log`** for fatal error stack traces
- **Re-attach with `prime-agent attach`** or resume with `--resume` to recover sessions without losing kernel state
- **Force `shutdown --force`** followed by `doctor --fix` as the nuclear option for unresponsive daemons

## Frequently Asked Questions

### What does `prime-agent doctor --fix` actually repair?

The `--fix` flag triggers automatic cleanup of stale Unix sockets, termination of orphaned worker processes, and daemon restart if the health check fails. This is implemented in [[`daemon-command.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-command.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/daemon-command.ts) using helpers from [[`daemon-ps.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-ps.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/daemon-ps.ts) like `runReap()` and `runShutdownAll()`.

### Where are PrimeAgent log files stored?

Logs live in `~/.prime/agent/` — specifically `pi-debug.log` for TUI diagnostics and `pi-crash.log` for fatal errors. The TUI writes these at [`tui/src/tui.ts#L1671-L1680`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts#L1671-L1680) and [`L1855-L1860`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts#L1855-L1860) respectively.

### How do I recover after a PrimeAgent crash?

First check `pi-crash.log` for the cause, then run `prime-agent --resume` to rehydrate your previous session state from disk. If the daemon itself crashed, run `prime-agent doctor --fix` before resuming. For specific agents, use `prime-agent attach <agent-id>` to reconnect without full session restore.

### Why does the daemon fail to start sometimes?

Stale socket files from previous unclean shutdowns block daemon startup. The `doctor` command detects these; run `prime-agent shutdown --force` to kill remaining processes, then `prime-agent doctor --fix` to remove socket files and restart cleanly.