agent-monitoring

Agent Monitoring

Efficient monitoring of Claude Code background agents through direct file reads. Avoids TaskOutput API calls that cost 100-500 tokens per check.

Quick Start

Check all running agents:

node scripts/agent-status.js

Tail specific agent output:

# Last 50 lines of agent output
tail -n 50 /path/to/agent/transcript.jsonl

Monitor multiple agents in parallel:

node scripts/multi-agent-monitor.js --interval 5000

Why Direct File Reads

For monitoring multiple parallel agents, direct file reads save thousands of tokens per session.

Agent Output Locations

Transcript Files

Claude Code stores agent transcripts as JSONL files:

~/.claude/projects/{project-hash}/{session-id}/transcripts/{agent-id}.jsonl

Or on Windows:

%USERPROFILE%\.claude\projects\{project-hash}\{session-id}\transcripts\{agent-id}.jsonl

Tracking Data

GoodVibes tracks running agents in:

{project}/.goodvibes/state/agent-tracking.json

Structure:

{
  "agent-123": {
    "agent_id": "agent-123",
    "agent_type": "backend-engineer",
    "session_id": "session-456",
    "started_at": "2024-01-15T10:30:00.000Z",
    "transcript_path": "/path/to/transcript.jsonl",
    "project": "/path/to/project",
    "project_name": "my-project"
  }
}

Workflows

1. List Running Agents

Check .goodvibes/state/agent-tracking.json:

const fs = require('fs');
const path = require('path');

function getRunningAgents(cwd) {
  const trackingPath = path.join(cwd, '.goodvibes', 'state', 'agent-tracking.json');

  if (!fs.existsSync(trackingPath)) {
    return [];
  }

  const tracking = JSON.parse(fs.readFileSync(trackingPath, 'utf-8'));
  return Object.values(tracking).map(agent => ({
    id: agent.agent_id,
    type: agent.agent_type,
    startedAt: agent.started_at,
    transcriptPath: agent.transcript_path,
    runtime: Date.now() - new Date(agent.started_at).getTime()
  }));
}

2. Tail Agent Output (Zero-Cost)

Read last N lines of transcript without API calls:

const fs = require('fs');

function tailTranscript(transcriptPath, lines = 50) {
  if (!fs.existsSync(transcriptPath)) {
    return { error: 'Transcript not found', lines: [] };
  }

  const content = fs.readFileSync(transcriptPath, 'utf-8');
  const allLines = content.split('\n').filter(Boolean);
  const lastLines = allLines.slice(-lines);

  return {
    totalLines: allLines.length,
    lines: lastLines.map(line => {
      try {
        return JSON.parse(line);
      } catch {
        return { raw: line };
      }
    })
  };
}

3. Detect Completion Status

Parse transcript to detect if agent has completed:

function detectAgentStatus(transcriptPath) {
  const { lines } = tailTranscript(transcriptPath, 100);

  const status = {
    isComplete: false,
    hasError: false,
    lastActivity: null,
    lastTool: null,
    summary: null
  };

  for (const event of lines.reverse()) {
    // Detect completion markers
    if (event.type === 'result' || event.type === 'stop') {
      status.isComplete = true;
    }

    // Detect errors
    if (event.type === 'error' || event.error) {
      status.hasError = true;
      status.errorMessage = event.error || event.message;
    }

    // Last tool used
    if (event.type === 'tool_use' && !status.lastTool) {
      status.lastTool = event.name;
    }

    // Last assistant message
    if (event.role === 'assistant' && event.content && !status.summary) {
      status.summary = typeof event.content === 'string'
        ? event.content.slice(0, 200)
        : JSON.stringify(event.content).slice(0, 200);
    }

    // Track last activity time
    if (event.timestamp && !status.lastActivity) {
      status.lastActivity = event.timestamp;
    }
  }

  return status;
}

4. Monitor Multiple Agents

Poll all running agents efficiently:

async function monitorAllAgents(cwd, options = {}) {
  const { interval = 5000, onUpdate } = options;
  const agents = getRunningAgents(cwd);

  const statuses = {};

  for (const agent of agents) {
    const status = detectAgentStatus(agent.transcriptPath);
    statuses[agent.id] = {
      ...agent,
      ...status,
      runtimeMs: Date.now() - new Date(agent.startedAt).getTime()
    };
  }

  if (onUpdate) {
    onUpdate(statuses);
  }

  // Check if all agents are done
  const allComplete = Object.values(statuses).every(s => s.isComplete);
  const anyError = Object.values(statuses).some(s => s.hasError);

  return {
    agents: statuses,
    allComplete,
    anyError,
    running: Object.values(statuses).filter(s => !s.isComplete).length,
    completed: Object.values(statuses).filter(s => s.isComplete).length
  };
}

Completion Detection Patterns

Success Indicators

Look for these in transcript events:

const SUCCESS_PATTERNS = [
  // Stop event with success
  { type: 'stop', success: true },

  // Result event
  { type: 'result' },

  // Assistant messages with completion phrases
  /completed|finished|done|success|all.*tests.*pass/i,

  // Final tool use patterns
  { type: 'tool_use', name: 'TodoWrite', status: 'completed' }
];

Error Indicators

Detect failures early:

const ERROR_PATTERNS = [
  // Explicit errors
  { type: 'error' },
  { error: true },

  // Tool failures
  { type: 'tool_result', is_error: true },

  // Assistant messages with error phrases
  /error|failed|exception|cannot|unable|permission denied/i,

  // Process exit codes
  { exitCode: /[^0]/ }
];

Stalled Agent Detection

Identify agents that may be stuck:

function detectStalled(transcriptPath, thresholdMs = 60000) {
  const { lines } = tailTranscript(transcriptPath, 10);

  if (lines.length === 0) {
    return { stalled: true, reason: 'no_activity' };
  }

  // Find most recent timestamp
  const lastEvent = lines.reverse().find(e => e.timestamp);
  if (!lastEvent) {
    return { stalled: false, reason: 'no_timestamps' };
  }

  const lastTime = new Date(lastEvent.timestamp).getTime();
  const elapsed = Date.now() - lastTime;

  if (elapsed > thresholdMs) {
    return {
      stalled: true,
      reason: 'inactive',
      lastActivityMs: elapsed,
      lastEvent: lastEvent.type || 'unknown'
    };
  }

  return { stalled: false, lastActivityMs: elapsed };
}

Transcript Event Types

Common Event Structure

interface TranscriptEvent {
  type: string;           // 'tool_use', 'tool_result', 'error', etc.
  timestamp?: string;     // ISO timestamp
  role?: 'user' | 'assistant' | 'system';
  content?: string | object;

  // Tool events
  name?: string;          // Tool name
  input?: object;         // Tool input parameters

  // Result events
  is_error?: boolean;
  error?: string;
  output?: string;
}

Key Event Types

Integration with GoodVibes Hooks

Using SubagentStart Hook Data

The GoodVibes SubagentStart hook records agent data:

// Access via hook telemetry
const tracking = require('./.goodvibes/state/agent-tracking.json');

// Each entry has:
// - agent_id: Unique identifier
// - agent_type: Type of agent (e.g., 'backend-engineer')
// - transcript_path: Path to output file
// - started_at: ISO timestamp

Combining with SubagentStop

After agent completion, telemetry is written to:

.goodvibes/telemetry/YYYY-MM.jsonl

Query historical agent performance:

# Find all completed agents this month
cat .goodvibes/telemetry/2024-01.jsonl | jq 'select(.event == "subagent_complete")'

Performance Tips

Efficient Polling

1. Start with long intervals (10s), decrease if needed
2. Stop polling when agent completes
3. Use file modification time before reading:

const fs = require('fs');

function hasNewActivity(transcriptPath, lastCheckMs) {
  try {
    const stats = fs.statSync(transcriptPath);
    return stats.mtimeMs > lastCheckMs;
  } catch {
    return false;
  }
}

Batch Operations

When monitoring multiple agents, read files in parallel:

async function batchCheckStatus(agents) {
  const promises = agents.map(async agent => {
    const status = detectAgentStatus(agent.transcriptPath);
    return { id: agent.id, ...status };
  });

  return Promise.all(promises);
}

Memory-Efficient Tailing

For very long transcripts, use streams:

const fs = require('fs');
const readline = require('readline');

async function streamTail(filePath, lineCount = 50) {
  const lines = [];
  const rl = readline.createInterface({
    input: fs.createReadStream(filePath),
    crlfDelay: Infinity
  });

  for await (const line of rl) {
    lines.push(line);
    if (lines.length > lineCount) {
      lines.shift();
    }
  }

  return lines;
}

Example: Full Monitoring Session

const fs = require('fs');
const path = require('path');

async function monitorBackgroundAgents(cwd) {
  console.log('Starting agent monitor...\n');

  const checkInterval = setInterval(async () => {
    const result = await monitorAllAgents(cwd);

    console.clear();
    console.log('=== Agent Status ===\n');

    for (const [id, agent] of Object.entries(result.agents)) {
      const runtime = Math.round(agent.runtimeMs / 1000);
      const status = agent.isComplete
        ? (agent.hasError ? 'FAILED' : 'DONE')
        : 'RUNNING';

      console.log(`[${status}] ${agent.type} (${id})`);
      console.log(`  Runtime: ${runtime}s`);
      console.log(`  Last tool: ${agent.lastTool || 'none'}`);
      if (agent.summary) {
        console.log(`  Summary: ${agent.summary.slice(0, 60)}...`);
      }
      console.log('');
    }

    console.log(`Running: ${result.running} | Completed: ${result.completed}`);

    if (result.allComplete) {
      clearInterval(checkInterval);
      console.log('\nAll agents complete!');

      if (result.anyError) {
        console.log('WARNING: Some agents encountered errors.');
      }
    }
  }, 5000);

  return checkInterval;
}

// Usage
monitorBackgroundAgents(process.cwd());

Scripts

• scripts/agent-status.js - Check status of all running agents
• scripts/multi-agent-monitor.js - Continuous monitoring dashboard
• scripts/tail-agent.js - Tail specific agent output

References

• references/transcript-format.md - Complete transcript event schema
• references/completion-patterns.md - Patterns for detecting agent states

Related Skills

• hook-integration - Integrate with SubagentStart/SubagentStop hooks
• task-decomposition - Plan parallel agent workflows