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

> Monitor PrimeAgent activity with our guide. Learn about daemon health, token flow, and session activity using CLI commands, TUI, RPC, and logs.

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

---

**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

```bash
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package-manager-cli.ts), which forwards to the daemon's internal state inspector.

### Machine-Readable JSON

```bash
prime-agent status --json

```

This emits a structured object suitable for automation:

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

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

```

### Ownership Validation

The companion file [`daemon-supervisor-ownership.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/interactive-mode.ts)) instantiates an `AgentActivityTracker` and feeds it events:

```typescript
// 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rpc-client.ts) at line 446) exposes `agent_messages_status`:

```typescript
// 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-supervisor.ts) manages log rotation. Default location:

```

<agentDir>/daemon.log

```

Derive the agent directory from the socket path:

```bash

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

```bash
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:

```typescript
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package-manager-cli.ts)
- **Daemon Supervisor** ([`daemon-supervisor.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-supervisor.ts)) maintains the socket listener and ownership lease; logs to rotating files via `appendRotatingLog`
- **Supervisor Ownership** ([`daemon-supervisor-ownership.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-supervisor-ownership.ts)) validates generation/PID/token claims between workers and the registry
- **Agent Activity Tracker** ([`agent-activity.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/daemon-supervisor.ts). If the socket disappears, the loop logs the failure and triggers supervisor restart election (documented at line 36 of [`daemon.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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.