Feature Request: Expose current agent information for external monitoring

Feature Request: Expose Current Agent Information for External Monitoring

Summary

Request to expose the currently active Claude Code agent in the statusline JSON, debug logs, or a dedicated file so that users can display agent status in their development environment (e.g., tmux status panes, terminal prompts, external monitoring tools).

Motivation

Claude Code supports multiple specialized agents (ios-developer, debugger, doctor, wesley, captain, etc.) that can be dynamically engaged during a session using the Task tool. However, there's currently no way for users to:

1. Monitor which agent is currently active in their terminal environment
2. Display agent status in custom status lines, tmux panes, or dashboards
3. Track agent switching during complex multi-agent workflows
4. Create automation based on which agent is running

This creates a disconnect between the powerful agent system and the user's awareness of which agent is handling their request.

Use Cases

1. Visual Status Indicators

Users want to display the current agent in:

• tmux status panes with color-coded agent indicators
• Terminal prompts showing active agent emoji/name
• External monitors for team awareness during pair programming
• IDE status bars for integrated development environments

2. Workflow Automation

Enable automation based on agent state:

• Auto-adjust terminal theme based on agent type
• Trigger specific hooks when certain agents engage
• Log agent transitions for performance analysis
• Route notifications differently per agent

3. Development Insights

Track agent usage patterns:

• Which agents are used most frequently
• How long each agent runs
• Agent switching patterns during problem-solving
• Performance metrics per agent type

Current Limitations

After investigating Claude Code's internals, agent information is not exposed in:

• ❌ Statusline JSON (session_id, model, workspace, etc. - no agent field)
• ❌ Debug logs (~/.claude/debug/*.txt - no agent invocation tracking)
• ❌ Transcript files (*.jsonl - sidechain flag exists but no agent type)
• ❌ Todo files (*-agent-*.json - created but empty)
• ❌ Process metadata (no agent info in process arguments)

Proposed Solution

Option 1: Add Agent Field to Statusline JSON (Preferred)

Extend the JSON input provided to statusline scripts with agent information:

{
  "session_id": "1e42f28d-584e-4d89-9421-44661286960c",
  "cwd": "/Users/Shared/Development/...",
  "model": {
    "id": "claude-sonnet-4-5-20250929",
    "display_name": "Sonnet 4.5"
  },
  "agent": {
    "active": true,
    "type": "ios-developer",
    "subagent_id": "98770f3f-224f-4d3f-a6ac-c315b57faa5f",
    "started_at": 1761058060365
  },
  "workspace": { ... },
  "cost": { ... }
}

When no agent is active:

{
  ...
  "agent": {
    "active": false,
    "type": null
  },
  ...
}

Benefits:

• ✅ Real-time updates via existing statusline refresh mechanism
• ✅ No additional file I/O or polling required
• ✅ Consistent with existing statusline architecture
• ✅ Easy for users to integrate into custom statusline scripts

Option 2: Create Agent Status File

Write current agent state to ~/.claude/current-agent.json:

{
  "active": true,
  "type": "ios-developer",
  "subagent_id": "98770f3f-224f-4d3f-a6ac-c315b57faa5f",
  "session_id": "1e42f28d-584e-4d89-9421-44661286960c",
  "started_at": 1761058060365,
  "updated_at": 1761058120500
}

Benefits:

• ✅ Simple file-based monitoring
• ✅ Can be monitored by any tool (watch, fswatch, etc.)
• ✅ Persists across statusline refresh cycles

Option 3: Enhance Debug Logging

Add agent state transitions to debug logs:

[DEBUG] Agent started: ios-developer (subagent_id: 98770f3f...)
[DEBUG] Agent stopped: ios-developer (duration: 45s)

Benefits:

• ✅ Useful for debugging agent behavior
• ✅ Provides historical agent usage data
• ❌ Requires log parsing (less ideal for real-time display)

Example Implementation (User Side)

With Option 1 implemented, users could easily display agent status:

Statusline Script

#!/usr/bin/env zsh
input=$(cat)

# Extract agent info
agent_active=$(echo "$input" | jq -r '.agent.active')
agent_type=$(echo "$input" | jq -r '.agent.type')

if [ "$agent_active" = "true" ]; then
    case "$agent_type" in
        "ios-developer") echo "📱 iOS Dev" ;;
        "debugger") echo "🐛 Debugger" ;;
        "doctor") echo "🏥 Doctor" ;;
        *) echo "🤖 $agent_type" ;;
    esac
fi

tmux Status Pane

# Monitor and display agent status in real-time
while true; do
    agent_info=$(cat ~/.claude/current-agent.json 2>/dev/null)
    # Display formatted agent status
    sleep 1
done

Additional Considerations

Agent Privacy

• Ensure agent information respects user privacy settings
• Don't expose sensitive prompt data, only agent type
• Allow opt-out via settings if needed

Performance

• Minimal overhead (agent state is already tracked internally)
• No additional API calls required
• Leverage existing refresh mechanisms

Backward Compatibility

• Add new fields without breaking existing statusline scripts
• Make agent field optional/nullable
• Document in statusline API changelog

Related Features

This feature request pairs well with:

• Custom agent definitions (already supported via ~/.claude/agents/)
• Agent hooks (for triggering actions on agent start/stop)
• Agent performance metrics (for tracking efficiency)

Community Interest

This feature would benefit:

• Power users who customize their development environments
• Teams using Claude Code for collaborative development
• Tool builders creating Claude Code integrations
• Researchers analyzing AI-assisted development workflows

References

• Current statusline documentation: https://docs.claude.com/en/docs/claude-code/statusline
• Agent system documentation: https://docs.claude.com/en/docs/claude-code/agents
• Related discussion: (if any GitHub issues exist)

---

Proposed by: @ehlersd
Date: 2025-10-21
Claude Code Version: 2.0.24