How to Monitor PrimeAgent's Activity: A Complete Guide to Daemon Health and Real-Time Tracking

PrimeAgent offers multiple monitoring pathways—CLI status commands, live TUI status lines, RPC subscriptions, and rotating log files—that expose daemon health, supervisor ownership, token flow, and session activity.

The PrimeAgent runtime from PrimeIntellect-ai tracks its own operation through a tightly integrated observability layer. Whether you need a quick health check from the command line, real-time visibility in the terminal UI, or programmatic access for external tools, the codebase provides purpose-built components for each use case. This guide covers all monitoring interfaces with specific file references from the repository.

CLI Monitoring with prime-agent status

The fastest way to assess PrimeAgent's current state is through the built-in status command.

Human-Readable Output

prime-agent status

This prints a concise table showing socket path, supervisor PID, active sessions, and heartbeat timestamp. The implementation lives in package-manager-cli.ts, which forwards to the daemon's internal state inspector.

Machine-Readable JSON

prime-agent status --json

This emits a structured object suitable for automation:

{
  "socketPath": "/tmp/prime-agent-12345.sock",
  "supervisorPid": 12345,
  "supervisorGeneration": "1",
  "activeSessions": 2,
  "heartbeat": { "lastSeen": "2026-08-14T13:42:10.123Z" }
}

The --json flag ensures stable field names for scripting. Parse this with jq or any JSON parser to extract specific values like socket paths for further inspection.

Supervisor Health and Ownership Tracking

The Daemon Supervisor component (daemon-supervisor.ts) is the core monitoring loop that validates PrimeAgent's liveness.

What the Supervisor Monitors

• Presence of the public supervisor Unix socket
• Worker heartbeats and connection state
• Ownership of the supervisor lease (generation, PID, token)

When the supervisor starts via DaemonSupervisor.start(), it creates a socket listener at this.socketPath and writes a supervisor config file (lines 1034-1038) containing:

// From daemon-supervisor.ts
const config = {
  generation: this.generation,
  pid: process.pid,
  token: this.token
};

Ownership Validation

The companion file daemon-supervisor-ownership.ts manages the SupervisorOwnershipRecord. Workers connecting to the supervisor receive an authentication claim via supervisorAuthenticationClaim() and validate it against the registry. Mismatches trigger errors like supervisor_generation_stale, which the startup routine catches and handles.

Log entries for ownership events use appendRotatingLog, defined in daemon-supervisor.ts, writing to daemon.log in the agent directory.

Real-Time Activity Tracking: Tokens and Status

For granular insight into what PrimeAgent is doing right now, the Agent Activity Tracker (agent-activity.ts) exposes live telemetry.

What Gets Tracked

Metric	Description
Token count	Cumulative and per-event token usage
Direction	Up (↑) for prompts, down (↓) for completions
Activity label	Human-readable state: "thinking", "working", "idle"

Event-Driven Updates

InteractiveMode (in interactive-mode.ts) instantiates an AgentActivityTracker and feeds it events:

// From agent-activity.ts usage pattern
activityTracker.handleEvent({
  type: "tool_result",      // or "llm_request", "sub_agent_complete", etc.
  tokens: 42,
  direction: "down"
});

The tracker maintains rolling state and exposes it through activityTracker.getStatus(), returning an AgentActivityStatus object.

TUI and RPC Status Pathways

PrimeAgent surfaces the same activity data through two interfaces depending on your interaction mode.

Terminal UI (TUI) Status Line

In interactive mode, the tracker feeds a status container rendered at the bottom of the screen. You will see live updates like:

↓ 123 tokens thinking

The InteractiveMode class wires the tracker's output to the UI panel's badge system, updating on every significant event.

RPC API for External Monitors

For headless or programmatic use, the RPC client (rpc-client.ts at line 446) exposes agent_messages_status:

// Programmatic monitoring via RPC (Node.js)
import { RpcClient } from "prime-agent/rpc-client";

async function monitor() {
  const client = await RpcClient.connect("/tmp/prime-agent-12345.sock");
  
  // Subscribe to live status updates
  client.on("agent_messages_status", (payload) => {
    const { statusKey, statusText } = payload;
    console.log(`Status [${statusKey}]: ${statusText}`);
  });
}

monitor();

RPC clients can poll this command or subscribe to server-sent events for push-based monitoring. The payload structure mirrors the TUI's internal representation, ensuring consistency across interfaces.

Log File Analysis for Debugging

For post-mortem analysis or deep inspection, PrimeAgent writes chronological logs to disk.

Log Location and Rotation

The appendRotatingLog function in daemon-supervisor.ts manages log rotation. Default location:

<agentDir>/daemon.log

Derive the agent directory from the socket path:

# Tail the persistent daemon log for detailed activity

tail -f $(prime-agent status --json | jq -r .socketPath | sed 's/.sock/.log/')

Diagnostic Command

The CLI provides a bundled diagnostic tool:

prime-agent doctor --full

This aggregates log excerpts, health checks, and configuration validation in one report.

Direct Tracker Access for Custom Extensions

If you are building on top of PrimeAgent, instantiate the tracker directly:

import { AgentActivityTracker } from "prime-agent/agent-activity";

const tracker = new AgentActivityTracker();
tracker.handleEvent({ type: "tool_result", tokens: 42 });

console.log(tracker.getStatus());
// → { tokens: 42, activity: "idle", direction: "down" }

This pattern is useful for custom modes or middleware that need to observe or augment activity reporting without modifying core daemon code.

Summary

• prime-agent status provides quick daemon health checks in human or JSON format, implemented in package-manager-cli.ts
• Daemon Supervisor (daemon-supervisor.ts) maintains the socket listener and ownership lease; logs to rotating files via appendRotatingLog
• Supervisor Ownership (daemon-supervisor-ownership.ts) validates generation/PID/token claims between workers and the registry
• Agent Activity Tracker (agent-activity.ts) collects token flow and activity labels, producing AgentActivityStatus objects
• TUI and RPC both consume activityTracker.getStatus()—the former renders status lines, the latter exposes agent_messages_status for programmatic use
• Log files at <agentDir>/daemon.log enable tail-based monitoring and post-mortem debugging

Frequently Asked Questions

How do I monitor PrimeAgent from a separate process or machine?

Use the RPC API. Connect via RpcClient to the supervisor socket path (discoverable via prime-agent status --json), then subscribe to agent_messages_status events. The RPC interface in rpc-client.ts provides the same live telemetry as the TUI without requiring terminal interaction.

Where does PrimeAgent store its supervisor state and logs?

Supervisor state—including generation, PID, and token—lives in a supervisor-config file written at startup (lines 1034-1038 in daemon-supervisor.ts). Logs rotate through <agentDir>/daemon.log as managed by appendRotatingLog. Both locations are relative to the agent directory, which you can extract from the socket path in status output.

What does the activity tracker's status object contain?

An AgentActivityStatus includes: tokens (cumulative count), activity (string label like "thinking" or "working"), and direction ("up" or "down" indicating token flow). This structure feeds both the TUI status line and the RPC agent_messages_status command, ensuring consistent reporting across interfaces.

How do I detect if the supervisor has crashed or lost its socket?

The Daemon Supervisor monitors socket presence through its event loop in daemon-supervisor.ts. If the socket disappears, the loop logs the failure and triggers supervisor restart election (documented at line 36 of daemon.md). For external detection, poll prime-agent status --json and check for null or stale heartbeat.lastSeen values, or tail daemon.log for socket-related error entries.

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