/agent-usage - Agent Usage Statistics
Display agent invocation statistics, usage patterns, and performance metrics.
System Prompt
EXECUTION DIRECTIVE: When /agent-usage is invoked, IMMEDIATELY query usage statistics.
Usage
/agent-usage # Summary statistics
/agent-usage --top 10 # Top 10 most used agents
/agent-usage --today # Today's usage
/agent-usage --week # Last 7 days
/agent-usage --agent NAME # Specific agent details
/agent-usage --unused # Show unused agents
/agent-usage --json # JSON output
/agent-usage --project PILOT # Filter to specific project (ADR-159)
Execution
~/.coditect/scripts/agent-usage.sh
~/.coditect/scripts/agent-usage.sh --top 10
~/.coditect/scripts/agent-usage.sh --today
~/.coditect/scripts/agent-usage.sh --agent senior-architect
Data Sources
- Context Database:
~/PROJECTS/.coditect-data/context-storage/sessions.db (ADR-118 Tier 3) - Session Logs:
~/.coditect/session-logs/ - Skill Learnings:
~/PROJECTS/.coditect-data/context-storage/skill-learnings.json
Output Format
Summary
======================================================================
Agent Usage Statistics
======================================================================
Period: Last 30 days
Total Invocations: 1,247
Top 10 Agents by Usage
----------------------
Rank Agent Count Success
---- ----- ----- -------
1. senior-architect 187 94.1%
2. codi-documentation-writer 156 97.4%
3. devops-engineer 134 91.0%
4. testing-specialist 98 95.9%
5. security-specialist 87 98.9%
6. database-architect 76 93.4%
7. frontend-react-typescript 72 96.5%
8. code-reviewer 65 100%
9. api-designer 58 94.8%
10. prompt-analyzer-specialist 52 88.5%
Usage by Category
-----------------
Architecture: 312 (25.0%)
Development: 298 (23.9%)
Documentation: 245 (19.6%)
DevOps: 187 (15.0%)
Security: 115 (9.2%)
Testing: 90 (7.2%)
Trends
------
vs. Previous Period: +12.3%
Most Improved: testing-specialist (+45%)
Declining: prompt-analyzer-specialist (-18%)
======================================================================
Agent Details (--agent NAME)
======================================================================
Agent: senior-architect
======================================================================
Total Invocations: 187
Success Rate: 94.1%
Avg. Duration: 45s
Recent Sessions (last 5)
------------------------
2026-01-15 04:30 Task A.10.2.1 SUCCESS 32s
2026-01-14 22:15 Task A.9.5.2 SUCCESS 67s
2026-01-14 18:00 Task A.9.4.1 FAILED 89s
2026-01-14 14:30 Task A.9.3.3 SUCCESS 41s
2026-01-14 10:00 Task A.9.2.1 SUCCESS 55s
Common Failure Reasons
----------------------
- Context limit exceeded (2 occurrences)
- Task unclear (1 occurrence)
Related Agents Often Used With
------------------------------
- database-architect (45% co-occurrence)
- security-specialist (32% co-occurrence)
======================================================================
Implementation
#!/usr/bin/env python3
import sqlite3
from collections import Counter
def get_agent_usage(db_path="~/PROJECTS/.coditect-data/context-storage/sessions.db (ADR-118 Tier 3)"):
conn = sqlite3.connect(db_path)
cursor = conn.cursor()
cursor.execute("""
SELECT agent_name, COUNT(*) as count,
SUM(CASE WHEN status='success' THEN 1 ELSE 0 END) * 100.0 / COUNT(*) as success_rate
FROM agent_invocations
WHERE timestamp > datetime('now', '-30 days')
GROUP BY agent_name
ORDER BY count DESC
LIMIT 10
""")
return cursor.fetchall()
Related Commands
| Command | Purpose |
|---|---|
/component-stats | Component counts |
/which | Find agents |
/optimize-skills | Skill optimization |
Version: 1.0.0 Created: 2026-01-15 Author: CODITECT Team