agentpulse-cli

---

Why Agent Pulse

Modern development often runs through several agent CLIs at once: Claude Code for refactors, Codex for implementation loops, Aider for pair-programming, Cursor for project edits, and other specialized tools for research or automation. Each tool keeps its own logs. Agent Pulse turns those scattered local traces into one operational view.

Preview

Agent Pulse
Unified activity dashboard for local AI coding agents

┌─ Last 24h ───────────────────────────────────────────────────────────────┐
│ Sessions       42        Tokens       3.8M        Est. cost      $18.42  │
│ Tool calls     316       Search          28        Active models      9  │
└──────────────────────────────────────────────────────────────────────────┘

Top sessions
┌──────────────┬───────────────┬─────────────┬────────┬───────┬──────────┐
│ Source       │ Model         │ Project     │ Tokens │ Tools │ Cost     │
├──────────────┼───────────────┼─────────────┼────────┼───────┼──────────┤
│ claude-code  │ claude-sonnet │ api         │ 842K   │ 61    │ $4.12    │
│ codex        │ gpt-5-codex   │ frontend    │ 516K   │ 44    │ $2.08    │
│ aider        │ deepseek      │ migrations  │ 203K   │ 12    │ $0.37    │
└──────────────┴───────────────┴─────────────┴────────┴───────┴──────────┘

Quick Start

pip install agentpulse-cli

# Try the dashboard with synthetic data
agent-pulse demo

# Check which local data sources are available
agent-pulse doctor

# Open the terminal dashboard
agent-pulse

Useful first commands:

agent-pulse status
agent-pulse top --sort cost
agent-pulse models
agent-pulse optimize
agent-pulse web --port 8765

Install optional web/API dependencies when you need the browser dashboard or REST server:

pip install "agentpulse-cli[web]"

Supported Agent Sources

Agent Pulse reads local logs only. It does not proxy model traffic and does not require API keys for normal dashboard usage.

Select sources per command:

agent-pulse -P claude -P codex -P aider
agent-pulse top -P cursor -P opencode --sort tokens

Or make it persistent in ~/.agent-pulse.toml:

monitor_platforms = "claude,codex,aider,cursor"
agent_log_home = "C:/Users/you"
hours = 24
limit = 30
theme = "nord"

Feature Map

Monitor

Analyze

Govern

Share and Integrate

Setup and Discovery

Package and Run

Common Workflows

Find the most expensive sessions

agent-pulse top --sort cost --hours 168
agent-pulse session <session-id>

Compare model efficiency

agent-pulse models --hours 168
agent-pulse leaderboard --rank-by efficiency
agent-pulse optimize

Put usage checks in CI

agent-pulse health --cost-limit 100 --token-limit 1000000 --json

Example GitHub Actions step:

- name: Check AI agent usage
  run: agent-pulse health --cost-limit 100 --json

Export a weekly report

agent-pulse report --period weekly
agent-pulse export-html -o agent-pulse-weekly.html --title "AI Usage Report"

Save and compare a point-in-time snapshot

agent-pulse snapshot save morning
agent-pulse snapshot save evening
agent-pulse snapshot diff morning evening

Expose data to other tools

agent-pulse api --port 8766
agent-pulse metrics --format prometheus
agent-pulse mcp --list-tools
agent-pulse mcp

Configuration

Run the setup wizard:

agent-pulse init

Or edit ~/.agent-pulse.toml directly:

# Data sources
hermes_db = "C:/path/to/hermes/state.db"
agent_log_home = "C:/Users/you"
monitor_platforms = "all"

# Display
theme = "default"
hours = 24
limit = 20
watch_interval = 5

# Alerts
alert_cost_threshold = 25.0
alert_token_threshold = 1000000

# Web
web_host = "127.0.0.1"
web_port = 8765

Disable individual log readers when you want a narrower scan:

claude_code = true
codex_code = true
aider = true
cursor_agent = false
antigravity = false
amp = false

Web Dashboard and API

The terminal dashboard is the default interface. For browser-based inspection, install the optional web extra and start the server:

pip install "agentpulse-cli[web]"
agent-pulse web --port 8765

For automation and internal dashboards:

agent-pulse api --port 8766

The API exposes status, sessions, projects, models, and health endpoints with generated OpenAPI documentation.

MCP Server

Agent Pulse can expose local usage data as MCP tools:

agent-pulse mcp --list-tools
agent-pulse mcp

Example MCP client configuration:

{
  "mcpServers": {
    "agent-pulse": {
      "command": "agent-pulse",
      "args": ["mcp"]
    }
  }
}

Use this when you want an assistant to answer questions like "which model was most expensive this week?" or "show the last high-token session" using local telemetry.

Data Accuracy

Agent Pulse reports estimates from local logs. It is designed for engineering visibility, budgeting, anomaly detection, and trend analysis.

Different CLIs expose different levels of detail. Agent Pulse preserves partial sessions instead of hiding them, so source and model coverage can improve without losing historical visibility.

Development

git clone https://github.com/Jane-o-O-o-O/agent-pulse.git
cd agent-pulse
pip install -e ".[dev,web]"

python -m pytest -q
python -m compileall agent_pulse

Project layout:

agent_pulse/
  cli.py              command surface
  core.py             session aggregation
  sources/            Hermes and agent-log readers
  renderers/          terminal and JSON output
  models/             shared session/project/stat models
tests/
  test_agent_log_sources.py

License

MIT. See LICENSE.