agent-pulse

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: agent-pulse
description: Use Agent Pulse to inspect local AI-agent activity across Hermes, Claude Code, Codex, DeepSeek, OpenClaw, Copilot, Aider, Qwen, OpenCode, Goose, Cursor, Antigravity, and Amp logs. Use when the user asks about AI-agent sessions, tokens, tool/search calls, model usage, estimated cost, budgets, forecasts, health checks, reports, setup diagnosis, web/API/metrics exports, or MCP integration.
---

# Agent Pulse

## Purpose

Use the installed `agent-pulse` CLI as the source of truth for local AI-agent activity. The PyPI package is `agentpulse-cli`, while the command remains `agent-pulse`. Prefer running commands and summarizing their output over reading the Agent Pulse source code.

Always enable UTF-8 on Windows before running commands because Agent Pulse output contains emoji and box drawing:

```powershell
$env:PYTHONUTF8='1'
$env:PYTHONIOENCODING='utf-8'
```

If `agent-pulse` is not on PATH, ask before installing dependencies. If the user approves, install the PyPI package or try running from a local project checkout:

```powershell
pip install agentpulse-cli
```

```powershell
python -m agent_pulse.cli --version
```

## Source Keys

Use `-P/--platform` when the user asks about one agent tool instead of all local data:

```text
hermes, claude, codex, deepseek, openclaw, copilot, aider, qwen,
opencode, goose, cursor, antigravity, amp
```

## Choose Commands

Use this command selection table first:

| User wants | Run |
|---|---|
| Current status | `agent-pulse status --json` |
| Full dashboard | `agent-pulse --json` or `agent-pulse --no-banner` |
| Demo data | `agent-pulse demo --json` |
| Setup diagnosis | `agent-pulse doctor --json` |
| Recent sessions | `agent-pulse --json --hours 24 --limit 20` |
| Top sessions | `agent-pulse top --sort tokens --json` |
| Top expensive sessions | `agent-pulse top --sort cost --json --hours 168` |
| Model cost analysis | `agent-pulse models --json` |
| Model ranking | `agent-pulse leaderboard --json --rank-by efficiency` |
| Cost savings | `agent-pulse optimize --json` |
| Budget status | `agent-pulse budget --json` |
| Cost forecast | `agent-pulse forecast --json` |
| Cost anomaly check | `agent-pulse anomaly --json` |
| Health/CI check | `agent-pulse health --json` |
| Composite score | `agent-pulse score --json` |
| Search sessions | `agent-pulse search "<query>" --json` |
| Compare periods | `agent-pulse compare --json` |
| Compare projects | `agent-pulse compare-projects --json` |
| Activity calendar | `agent-pulse heatmap --json` |
| Smart recommendations | `agent-pulse insights --json` |
| Prometheus metrics | `agent-pulse metrics --format prometheus` |
| Export report | `agent-pulse export -f markdown` or `agent-pulse export-html` |
| Web dashboard | `agent-pulse web --port 8765` |
| REST API | `agent-pulse api --port 8766` |
| MCP tools | `agent-pulse mcp --list-tools` |

If the installed command lacks an option, run `agent-pulse <command> --help` and adapt.

## Workflow

1. Start with `agent-pulse doctor --json` only when the user asks why data is missing, asks for setup help, or a normal data command returns no sessions.
2. Use JSON output whenever possible. Summarize the fields that matter: sessions, tokens, tools, search calls, model breakdown, source breakdown, estimated cost, warnings.
3. Use time filters for scoped questions. Default to 24 hours for "recent" and 168 hours for "this week":

```powershell
agent-pulse status --json --hours 24
agent-pulse --json --hours 168 --limit 50
```

4. Use platform filters when the user asks about a specific agent system:

```powershell
agent-pulse --json -P codex --hours 24
agent-pulse --json -P claude --hours 24
agent-pulse top --json -P aider --sort cost
agent-pulse status --json -P cursor
```

5. For cost questions, pair summary, model, and top-session views:

```powershell
agent-pulse status --json --hours 24
agent-pulse models --json --hours 24
agent-pulse top --sort cost --json --hours 24
agent-pulse