Skip to main content
Glama
anirudhprashant

agent-vitals

by anirudhprashant
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

30-second install

uv tool install git+https://github.com/anirudhprashant/agent-vitals
av install     # finds every agent host on your machine and wires up MCP + a priming skill

Restart your agent host. From then on it calls vitals_summary before risky work, without you asking.

NOTE

An unrelated package calledagent-vitals exists on PyPI. Install from this repo as shown above.

Related MCP server: codinfy-agent-monitor

The difference

You:   schedule a daily backup at 2am
Agent: done.

  0 2 * * * /home/me/backup.sh

backup.sh doesn't exist. The cron job fails silently, every night, forever.

You:   schedule a daily backup at 2am
Agent: checking first.

  → shadow_stale     no broken jobs
  → backup.sh        exists, executable
  → crontab updated
  → shadow_stale     still clean ✓
You:   is my agent setup healthy?
Agent: looks fine to me!

(it has no idea)

You:   is my agent setup healthy?
Agent: → vitals_summary

  shadow: 13 autonomous things configured
  claude code (7d): ⚠ 36 stuck sessions

How it works

  1. Install. av install registers the MCP server and a priming skill with each host it finds.

  2. Observe. The skill tells the agent when to call which tool. Optional hooks go further and refuse crontab and systemctl --user changes until vitals has been checked.

  3. Improve. av cost, av loops and av coach turn your own session history into cheaper, less loopy agents.

Everything is local and read-only. Session traces are summarised by structure, never by content, so no payloads or secrets leave the log files.

What it catches

Stale automation

Cron jobs, systemd timers, MCP servers and scheduled skills that point at things which no longer exist

Stuck sessions

Per-agent completion rates, trends, and sessions that look stuck

Doom loops

Exact and soft repeats in Bash and Edit calls, with polling excluded and edits compared by content

Dead weight

MCP servers and tools you never call, each of which costs context on every turn

Spend

Model-aware token cost, an Effective Tokens metric, and model downgrade suggestions

SSH polling

The same command sent to the same host over and over

Overlap

Duplicate or near-identical tools across MCP servers

Bloat

Compaction for oversized session files, with a backup and a dry run first

MCP tools

The 13 tools your agent can call. All are read-only and safe to call repeatedly.

Tool

Use it

vitals_summary

First, before any non-trivial task, or when something feels off

shadow_list

Before infra changes: everything running on your behalf

shadow_stale

Before claiming cron is fine, or scheduling new work

burnout_summary

After long tasks, to compare against baseline

burnout_stuck_sessions

When a loop is suspected

trace_list · trace_summary

Find and summarise recorded sessions

trace_diff

Compare a good run with a bad one

trace_errors · trace_grep

Only the failures, or only one tool

trace_profile · trace_export · trace_suggest

Per-tool timings, JSON export, and concrete fixes

Pre-action hooks

Priming asks the agent to check. Hooks enforce it.

av hooks install     # one-time, about 3 seconds
av hooks status
av hooks disable     # or: av hooks uninstall
  ⚡ vitals hook: refused `crontab -e`

  reason:   vitals stamp is 5m12s old, exceeds 60s window
  refresh:  call any vitals tool or run `av doctor`
  bypass:   VITALS_BYPASS=1 crontab -e

Gated: crontab -e/-r/-i/<file> and systemctl --user state changes. Never gated: reads (crontab -l, systemctl status, list-*) and power management. A stale stamp will never block a reboot.

CLI

av                  # one-shot health summary
av doctor           # summary + what to fix
av shadow [--watch] # everything configured on this machine
av burnout          # completion metrics, last 7 days
av drift            # inconsistencies across hosts
av loops            # doom-loop detector
av unused           # MCP servers and tools you never call
av cost             # spend, Effective Tokens, downgrade ideas
av tokens [--suggest]
av ssh             # repeated SSH polling to the same host
av overlap         # duplicate tools across MCP servers
av sessions        # session files with age and size
av snapshot        # tar.gz of agent state (MCP configs, skills, hooks)
av detect          # list detected agent hosts
av mcp             # run the MCP server (stdio)
av init            # old alias for `av install`
av compact [--dry-run]
av coach            # system prompts built from your real sessions
av trace list | summary | replay | diff | errors | profile | grep | export | suggest | watch

Supported hosts

Host

MCP config

Priming

Claude Code

~/.claude/.mcp.json

~/.claude/skills/vitals/SKILL.md

pi

~/.pi/agent/mcp.json

~/.claude/skills/vitals/SKILL.md

Cursor

~/.cursor/mcp.json

~/.cursor/rules/vitals.md

OpenCode

~/.config/opencode/mcp.json

~/.config/opencode/AGENTS.md

Codex CLI

~/.codex/config.toml

~/.codex/AGENTS.md

av install is idempotent: re-running it skips existing entries and never duplicates them.

Roadmap

  • 0.1 shadow and burnout

  • 0.2 MCP server, av install for five hosts

  • 0.3 pre-action hooks

  • 0.6 efficiency suite: loops, unused, cost, tokens, ssh, overlap, compact, coach

  • 0.7 trace suite for Claude Code and pi sessions

  • shadow live: running agent processes as a tree

  • Agent déjà vu: "you researched this codebase three weeks ago"

Contributing

  • Scanners in src/agent_vitals/scanners.py are independent and fail gracefully. Add a source by writing one scan_*() function and registering it in scan_all().

  • Tool docstrings are the product. The agent reads them as instructions, so write them as directives ("call this first when…"), not API docs.

  • Run pytest -q. CI tests Python 3.11 to 3.13.

About 6,000 lines of Python and 300+ tests. Built with typer, rich and FastMCP.

This server cannot be deployed

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Monitor

    Partha-SUST16
    A
    license
    Not graded
    quality
    C
    maintenance
    An observability tool for agentic AI pipelines that intercepts MCP and Python tool calls to provide real-time metrics, session replays, and alerts via a local dashboard. It enables centralized monitoring of multiple MCP servers through multiplexer and proxy modes without requiring changes to existing agent code.
    3
    MIT

  • codinfy-agent-monitor

    bakalagoin
    F
    license
    Not graded
    quality
    C
    maintenance
    Provides real-time monitoring of AI agents, context, usage limits, workflows, files, Git, tests, builds, errors, secrets, and model-economy advice for tools like Claude Code, Codex, and Cursor, with 30 MCP tools for comprehensive observability.
    1
    -

  • AIS Revizor

    bswvladimir-beep
    F
    license
    Not graded
    quality
    D
    maintenance
    A local-first MCP server that gives AI coding agents runtime visibility and AI-managed debug logging. It replaces blind print() debugging by turning runtime execution into causal chains, allowing agents to instantly locate bugs by finding missing .success events in Python and TypeScript code. Single binary with MCP, CLI, and HTTP interfaces.
    -