agent-pulse

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:

$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:

pip install agentpulse-cli

Source Keys

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

Choose Commands

Use this command selection table first:

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":

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

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

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

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

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:

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:

For monitoring pipelines:

MCP

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

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: