How to Debug Issues in PrimeAgent: Complete Troubleshooting Guide

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
Doctor logic	Runs health checks and optional repairs	[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/packages/coding-agent/src/cli/daemon-ps.ts)

Basic Doctor Usage

# 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.

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
pi-crash.log	Fatal crash stack traces	tui/src/tui.ts#L1855-L1860

Reading the Debug Log

# 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

# 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

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

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:

prime-agent doctor --fix --json

The repair routine in [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

# 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:

# 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:

# 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

# 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

# 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

# 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:

#!/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/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/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/packages/coding-agent/src/cli/daemon-command.ts) using helpers from [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 and 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.

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