Prime Agent Troubleshooting: Common Issues and Fixes for PrimeIntellect-ai/prime-agent

The most common Prime Agent problems involve daemon crashes, authentication failures, session persistence errors, and worker/kernel timeouts—all diagnosable with built-in doctor commands and environment variable fixes.

Prime Agent is a multi-process, daemon-backed coding assistant built around a Recursive Language Model (RLM) and persistent IPython kernel. Because it combines CLI/TUI front-ends, supervisor daemons, worker processes, and pluggable model providers, failures can surface across multiple layers. This guide covers the eight most frequent Prime Agent troubleshooting scenarios, their root causes in the source code, and actionable fixes.

Installation Failures and Fixes

The curl … | sh installer or npm ci builds occasionally fail due to environment mismatches.

Root causes:

• Node.js version below 22.8.0
• Outdated npm workspace identifiers
• Missing /usr/local/bin in $PATH on macOS/Linux

Solutions:

# Verify Node version (required: ≥ 22.8.0)

node --version

# Clean install from source

git clone https://github.com/PrimeIntellect-ai/prime-agent.git
cd prime-agent
npm ci

# Ensure binary is reachable

export PATH="/usr/local/bin:$PATH"
prime-agent --version

If the prime-agent binary remains missing, the install script likely failed to link the CLI. Re-run with curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh and check for network errors.

Authentication and API Key Problems

Prime Agent stores provider credentials in ~/.prime/agent/auth.json. Authentication failures typically produce "/login returns provider not found" or rejected model calls.

Resolution steps:

1. Run /login inside an active Prime Agent session to select a provider interactively.

2. Export the correct environment variable for your provider:

   export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
   export OPENAI_API_KEY=sk-xxxxxxxxxxxx

3. Clear stale credentials if keys were rotated:

   rm ~/.prime/agent/auth.json

The authentication flow does not validate keys until the first model call, so a silent failure may only surface during inference.

Daemon and Supervisor Crashes

The prime-agent status command reporting "daemon not running" or Error: Sessions directory not found indicates supervisor failure. This logic resides in packages/coding-agent/src/daemon/ with validation in scripts/tool-stats.ts.

Diagnostic commands:

# Check daemon health

prime-agent status

# Auto-repair directories and PID files

prime-agent doctor --fix

# View recent crash logs

prime-agent doctor --log

# Nuclear option: kill all processes and restart

pkill -f prime-agent
prime-agent

The daemon creates ~/.prime/agent/sessions/ for persistence. If this directory is missing or permissions are restricted, scripts/tool-stats.ts throws throw new Error('Sessions directory not found…') as referenced in the source.

Worker, Kernel, and LSP Connection Failures

Truncated model output, Error: peer unavailable, or Timed out waiting for snapshot indicate worker process death or IPython kernel disconnection.

Required environment:

• Python ≥ 3.10 with ipykernel installed
• Valid PRIME_AGENT_KERNEL_PYTHON pointing to interpreter

# Force interpreter selection

export PRIME_AGENT_KERNEL_PYTHON=$(which python3)

# Verify kernel availability

python3 -m ipykernel --version

# Re-attach to surviving session after crash

prime-agent agents                    # list session IDs

prime-agent attach <session-id>

Kernel sockets can break during long sessions. If prime-agent attach fails with peer errors, the kernel process died—start a fresh session and migrate context manually.

Session Persistence and Snapshot Errors

Sessions disappear or fail to load when JSONL files in ~/.prime/agent/sessions/ are corrupted or missing.

Verification steps:

# List session storage

ls ~/.prime/agent/sessions/

# View live sessions (may differ from disk if daemon crashed)

prime-agent agents

# Force cleanup of zombie workers

prime-agent shutdown --force

Corrupted session files cannot be repaired—Prime Agent does not implement automatic backup snapshots. For critical work, export sessions periodically or rely on external version control.

Model Provider Errors and Rate Limits

"Network failed", "offline", and "provider returned an error" map to three distinct causes:

Symptom	Check	Command
Network layer	API connectivity	curl https://api.anthropic.com/v1/models
Rate limiting	HTTP 429 responses	Switch via /model or Ctrl+L
Subscription status	Account dashboard	Verify at provider portal

The /model TUI command (Ctrl+L) hot-swaps providers without restart, implemented in packages/tui/src/tui.ts error propagation paths.

Tool and Skill Execution Failures

Error: expected tool metadata, disk offline, or "cannot edit file" indicate plugin or permission problems.

Fixes:

• Install missing skill: npm i @prime/skill-example
• Grant workspace permissions: Run Prime Agent from a writeable directory, not system paths
• Check sandbox restrictions: Some skills require explicit file-system access grants

Skill plugins load dynamically; missing metadata errors occur when npm packages lack the required prime-skill manifest fields in package.json.

TUI and CLI Interface Glitches

Keyboard shortcuts (Ctrl+O, Ctrl+P, mouse events) fail in terminals lacking proper escape sequence support.

Compatible terminals: iTerm2, Kitty, GNOME Terminal, Windows Terminal

tmux-specific fix:

# Fixed-size session prevents resize glitches

tmux new-session -d -s prime -x 80 -y 24
prime-agent

The TUI core in packages/tui/src/tui.ts throws throw new Error(errorMsg) for rendering failures—often masking as hangs when the terminal does not respond to cursor position queries.

Performance Degradation and Timeouts

Long-running sessions become sluggish due to scheduler overload, high autonomous token budgets, or background job accumulation.

Mitigation commands:

# Reduce autonomous effort

/effort low

# Throttle periodic background work

/heartbeat 30

# Inspect process tree for runaway tasks

/tree

Use /tree to identify stuck child processes. The RLM scheduler does not auto-kill runaway tool chains without explicit heartbeat timeouts.

Summary

• Installation: Verify Node ≥ 22.8.0 and run npm ci from clean checkout
• Authentication: Export provider API keys and clear ~/.prime/agent/auth.json if stale
• Daemon crashes: Use prime-agent doctor --fix and pkill -f prime-agent for recovery
• Kernel failures: Set PRIME_AGENT_KERNEL_PYTHON and re-attach with prime-agent attach
• Session loss: Check ~/.prime/agent/sessions/ and force shutdown stray workers
• Provider errors: Test connectivity with curl, switch models via /model
• Skill errors: Install missing npm packages and verify write permissions
• TUI glitches: Use modern terminals or fixed-size tmux sessions
• Performance: Reduce /effort, configure /heartbeat, monitor with /tree

Frequently Asked Questions

Why does Prime Agent say "daemon not running" immediately after installation?

The supervisor daemon failed to start, usually due to missing ~/.prime/agent/sessions/ directory or stale PID files from a previous crash. Run prime-agent doctor --fix to auto-repair directories, or manually run pkill -f prime-agent followed by prime-agent to clear orphaned processes.

Where does Prime Agent store API keys and session data?

Credentials live in ~/.prime/agent/auth.json. Session persistence uses JSONL files in ~/.prime/agent/sessions/. Both paths are validated at startup; scripts/tool-stats.ts throws explicit errors if directories are absent according to the source implementation.

How do I recover a session after the IPython kernel crashes?

First attempt prime-agent attach <session-id> after listing IDs with prime-agent agents. If this fails with "peer unavailable," the kernel process died and cannot be recovered—start a new session. Set PRIME_AGENT_KERNEL_PYTHON explicitly to prevent interpreter mismatches.

Can I run Prime Agent in tmux or over SSH?

Yes, but terminal capabilities vary. Use modern terminals (iTerm2, Kitty, GNOME Terminal) supporting mouse and escape sequences. For tmux, create sessions with fixed dimensions: tmux new-session -d -s prime -x 80 -y 24. SSH works provided the remote host meets Python ≥ 3.10 and Node ≥ 22.8.0 requirements.

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