name: status-agents description: Show real-time status of all agents from .claude-code/ui-state.json

Agent Status Command

Read the .claude-code/ui-state.json file and display the current status of all agents in a formatted table.

Implementation Instructions

When this command is invoked, follow these steps:

1. Read UI State File

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

const uiStatePath = path.join(process.cwd(), '.claude-code/ui-state.json');
let state;

try {
  const content = await fs.readFile(uiStatePath, 'utf8');
  state = JSON.parse(content);
} catch (error) {
  console.log('Agent system not yet initialized');
  console.log('');
  console.log('The .claude-code/ui-state.json file doesn\'t exist yet.');
  console.log('This file is created automatically when agents start executing.');
  return;
}

2. Helper Functions

function timeAgo(isoTimestamp) {
  if (!isoTimestamp) return 'never';
  const now = new Date();
  const past = new Date(isoTimestamp);
  const diffMs = now - past;

  const seconds = Math.floor(diffMs / 1000);
  const minutes = Math.floor(seconds / 60);
  const hours = Math.floor(minutes / 60);
  const days = Math.floor(hours / 24);

  if (days > 0) return `${days}d ago`;
  if (hours > 0) return `${hours}h ago`;
  if (minutes > 0) return `${minutes}m ago`;
  if (seconds > 0) return `${seconds}s ago`;
  return 'just now';
}

function elapsedTime(startIsoTimestamp) {
  const start = new Date(startIsoTimestamp);
  const now = new Date();
  const diffMs = now - start;
  return (diffMs / 1000).toFixed(1);
}

3. Display Format

Agent System v[agent_system_version]

===================================================================

[ACTIVE AGENTS SECTION - only if any agent has status='active']
ACTIVE AGENTS ([count]):
[agent-name]    Running: "[current_task]" ([duration]s elapsed)

[IDLE AGENTS SECTION]
IDLE AGENTS ([count]):
[agent-name]
   Last: "[last_task]" ([time-ago])
   Success: [success_count] | Failures: [failure_count]

[Or if never executed:]
[agent-name]
   Never executed
   Description: [description]

===================================================================

WORKFLOW STATUS:
[If active_workflow !== null]
Active Workflow: [workflow_name]
   Strategy: [strategy]
   Progress: Step [step]/[total_steps]

[If active_workflow === null]
No active workflow

===================================================================

SYSTEM STATS:
- Total Agent Executions: [metadata.total_agent_executions || 0]
- Last Updated: [metadata.last_updated] ([time-ago])
- Agent System Version: [agent_system_version]
===================================================================

4. Sort Order

• Active agents: by agent name alphabetically
• Idle agents: by last_execution descending (most recent first), null/never executed last

Usage

/status-agents

Notes

• This command is read-only (no modifications to ui-state.json)
• Updates in real-time as agents execute
• Useful for debugging and monitoring agent activity
• Can be called at any time during conversation
• If .claude-code/ directory doesn't exist, gracefully shows initialization message