agent-pulse

interface:
  display_name: "Agent Pulse"
  short_description: "Inspect AI-agent sessions, tokens, model costs, and health."
  default_prompt: "Use $agent-pulse to summarize my recent AI-agent sessions, token usage, model costs, health, and forecast."

"""Run a compact Agent Pulse usage snapshot."""

from __future__ import annotations

import argparse
import json
import os
import shutil
import subprocess
import sys


def command_base() -> list[str]:
    if shutil.which("agent-pulse"):
        return ["agent-pulse"]
    return [sys.executable, "-m", "agent_pulse.cli"]


def run(args: list[str], timeout: int) -> dict:
    env = os.environ.copy()
    env.setdefault("PYTHONUTF8", "1")
    env.setdefault("PYTHONIOENCODING", "utf-8")
    cmd = command_base() + args
    try:
        proc = subprocess.run(
            cmd,
            text=True,
            stdout=subprocess.PIPE,
            stderr=subprocess.STDOUT,
            env=env,
            check=False,
            timeout=timeout,
        )
    except subprocess.TimeoutExpired as exc:
        raw_output = (exc.stdout or "").strip() if isinstance(exc.stdout, str) else ""
        return {
            "command": " ".join(cmd),
            "exit_code": None,
            "timed_out": True,
            "timeout_seconds": timeout,
            "output": raw_output or f"Command timed out after {timeout} seconds.",
        }

    raw = proc.stdout.strip()
    parsed = None
    if raw:
        try:
            parsed = json.loads(raw)
        except json.JSONDecodeError:
            parsed = raw
    return {"command": " ".join(cmd), "exit_code": proc.returncode, "timed_out": False, "output": parsed}


def main() -> int:
    parser = argparse.ArgumentParser(description="Run a compact Agent Pulse JSON snapshot.")
    parser.add_argument("--hours", type=int, default=24, help="Recent activity window in hours.")
    parser.add_argument("--days", type=int, default=7, help="Trend/insight window in days.")
    parser.add_argument("--limit", type=int, default=10, help="Top-session limit.")
    parser.add_argument(
        "--command-timeout",
        type=int,
        default=20,
        help="Timeout in seconds for each Agent Pulse subcommand.",
    )
    args = parser.parse_args()

    hours = str(args.hours)
    days = str(args.days)
    limit = str(args.limit)
    trend_hours = str(args.days * 24)
    timeout = args.command_timeout

    snapshot = {
        "doctor": run(["doctor", "--json"], timeout),
        f"status_{args.hours}h": run(["status", "--json", "--hours", hours], timeout),
        "top_cost": run(
            ["top", "--sort", "cost", "--json", "--hours", trend_hours, "--limit", limit],
            timeout,
        ),
        "models": run(["models", "--json", "--hours", trend_hours], timeout),
        "leaderboard": run(["leaderboard", "--json", "--hours", trend_hours], timeout),
        "forecast": run(["forecast", "--json", "--days", days], timeout),
        "health": run(["health", "--json"], timeout),
        "score": run(["score", "--json", "--hours", trend_hours], timeout),
        "budget": run(["budget", "--json"], timeout),
        "insights": run(["insights", "--json", "--days", days], timeout),
    }
    print(json.dumps(snapshot, indent=2, ensure_ascii=False))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

---
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 optimize --json --hours 168
```

6. For trend and risk questions, use forecast/history/compare/anomaly:

```powershell
agent-pulse forecast --json
agent-pulse history --json
agent-pulse compare --json
agent-pulse anomaly --json
```

7. For setup, use the discovery commands before guessing paths:

```powershell
agent-pulse doctor --json
agent-pulse scan --json --details
agent-pulse config show
```

## Interpreting Results

- Treat `total_cost_usd` as an estimate based on Agent Pulse's local model pricing table.
- Report both cost and token volume; low-cost models can still have very high token usage.
- Distinguish sources such as `codex`, `claude`, `hermes`, `deepseek`, `openclaw`, `aider`, `cursor`, `opencode`, and `goose`.
- Mention if `doctor` reports missing optional sources, missing `dev_root`, or optional web dependencies.
- If no sessions appear, check `doctor`, then try a wider time window such as `--hours 168`.
- Check whether the user asked for a source (`-P`) filter, a model filter, or a project comparison before giving overall totals.
- If a command emits plain text instead of JSON or fails because an installed version is older, run `agent-pulse <command> --help` and use the closest supported option.

## Reports

For a short human-readable answer, run JSON commands and summarize.

For artifacts, prefer:

```powershell
agent-pulse report --period daily
agent-pulse export -f markdown
agent-pulse export-html
```

Do not invent exact savings or costs. Use the CLI output.

## Integrations

Use the web and API extras only when the user asks for a browser dashboard or programmatic server. Ask before installing missing extras:

```powershell
pip install "agentpulse-cli[web]"
agent-pulse web --port 8765
agent-pulse api --port 8766
```

For monitoring pipelines:

```powershell
agent-pulse metrics --format prometheus
agent-pulse health --cost-limit 100 --token-limit 1000000 --json
```

## MCP

Use MCP mode when the user wants other AI clients to query Agent Pulse:

```powershell
agent-pulse mcp --list-tools
agent-pulse mcp
```

When explaining MCP, mention that it exposes tools such as status, forecast, top sessions, model analytics, optimization, health, search, and leaderboard.

## Local Helper

This skill includes `scripts/run_agent_pulse_snapshot.py`, which runs a compact set of JSON-friendly Agent Pulse checks and prints a combined summary:

```powershell
python scripts/run_agent_pulse_snapshot.py --hours 24 --days 7
```