v0.5.0 — efficiency suite

v0.5.0 — efficiency suite

Three new tools to make your agent stack cheaper and more reliable.

av loops — doom-loop detection (content-aware, v0.5.1 fix)

Scans every session for repeated identical tool calls and file edits.

• Tool loops: exact same Bash command string repeated 20+ times.
• File loops: exact same Edit (same old_string + new_string) applied 10+ times.
• Polling commands excluded: ps, pgrep, pidof, /proc checks are not flagged. Waiting for a process to exit is legitimate, not a loop.
• Content-aware: file edits are compared by actual content, not just count. Progressive changes to the same file are not flagged.

Verified against your actual session data: 0 false positives. Previously flagged sessions (pipeline.py, sterling_auto.py, chatly-server.js) were all progressive edits, not loops. The highest tool_repeat was 28 ps polls of a mempalace repair process — correctly excluded.

av unused — registered-but-unused MCP tool detector

Every registered MCP tool ships its JSON schema in every agent turn. GitHub measured 8–12KB of pure overhead per turn from tools the agent never uses. Cross-references registered tools against session data to find the dead weight.

av cost now reports Effective Tokens (ET)

Using GitHub's formula from their token-efficiency post:

ET = m * (1.0*I + 0.1*C + 1.0*W + 4.0*O)

Where m is model multiplier (Haiku 0.25x, Sonnet 1x, Opus 5x), I is input, C is cache_read, W is cache_write, O is output. Output is weighted 4x (most expensive across all providers); cache_read is 0.1x (served from cache at fraction of the cost).

Stats

• 14 CLI commands
• 5 MCP tools
• ~2700 LOC
• 203 tests across 8 modules
• MIT

v0.4.0 — the full suite

v0.4.0 — agent-vitals becomes a real suite

v0.1.0 was two CLI commands. v0.2.0 added the MCP server. v0.3.0 added the gate. v0.4.0 turns it into a comprehensive observability + maintenance suite for agentic harnesses — 9 CLI commands, 5 MCP tools, 175 tests.

New in v0.4.0

av install — interactive installer

Replaces av init + av hooks install with a single guided flow:

$ av install
  detected 3 agent host(s):
    - pi           /home/anirudh/.pi/agent/mcp.json
    - Claude Code  /home/anirudh/.claude/.mcp.json
    - Codex CLI    /home/anirudh/.codex/config.toml

  what to install:
    1. mcp       — register agent-vitals as an MCP server in detected hosts
    2. priming   — drop a SKILL.md so the agent knows when to call vitals
    3. hooks     — PATH wrappers around crontab / systemctl
    4. snapshot  — take a backup of current agent state first
  components [default]: 1 4

  which hosts to install for?
    1. pi
    2. Claude Code
    3. Codex CLI
  hosts [default: all]: 1 2

  snapshot: /home/anirudh/agent-vitals-snapshots/.../pre-install.tar.gz

  [pi] mcp: added
  [Claude Code] mcp: added
  [Codex CLI] mcp: added
  [pi] priming: installed
  [Claude Code] priming: installed
  [Codex CLI] priming: installed

Non-interactive: av install --yes or av install --only=hooks,drift.

av drift — find inconsistencies across agent hosts

$ av drift
drift: 2 finding(s)

  [high] (1)
    - mcp_drift: mempalace
      registered differently across 2 hosts: ['Claude Code', 'pi']
      (one uses `mempalace-mcp --palace ~/.mempalace`, the other uses
      the full path to .local/bin/mempalace-mcp)

  [low] (1)
    - mcp_dup: agent-vitals
      same target registered in 2 hosts: ['Claude Code', 'pi']
      (intentional multi-host — both correctly call `av mcp`)

av cost — token spend tracker

$ av cost
cost: token usage by host / project (last scan; pricing rough)

  [claude-code]
    -home-anirudh--claude-mem-observer-sessions  248,616,367 tok   ~29.53
    subagents                                  437,466,273 tok   ~62.47

  total: 686,082,640 tokens, ~92.00
  (pricing is conservative Sonnet-class default; actual may differ)

av sessions — list session files

$ av sessions --older-than 30 --limit 5
sessions: 47 file(s) older than 30d, 142.3 MiB total
  host             age       size   events  project
  claude-code     45.2d    2.1M     1234  --home-anirudh--old-feature
  claude-code     38.1d    1.8M      892  --home-anirudh--experiments
  ...

av snapshot — backup agent state

$ av snapshot
✓ snapshot created: ~/agent-vitals-snapshots/agent-vitals-snapshot-20260710T231825Z.tar.gz (2665K, 577 files)
  restore: tar -xzf <file> -C /tmp/restore  # then copy files back manually

What v0.4.0 doesn't yet do

• drift, cost, sessions, snapshot are CLI-only. Not yet exposed as MCP tools. Scheduled for v0.5.0.
• Integration tests are removed. They were failing under uv run due to env-var interaction with Typer subcommand routing. Unit tests cover the same logic more thoroughly.

Stats

• 9 CLI commands: install · doctor · detect · mcp · shadow · burnout · drift · cost · sessions · snapshot · hooks
• 5 MCP tools: vitals_summary · shadow_list · shadow_stale · burnout_summary · burnout_stuck_sessions
• ~2400 LOC of Python
• 175 unit tests across 7 modules
• 0 runtime dependencies beyond typer, rich, pyyaml, mcp

License

MIT.

v0.3.0 — pre-action hooks (priming → enforcement)

v0.3.0 — Make the agent less stupid, for real this time

v0.2.0's priming was 30–40% effective — the SKILL.md put hints in front of the agent's face, but the agent could still write a crontab entry without calling shadow_stale. v0.3.0 closes that gap with pre-action hooks that gate mutations at the OS level.

What's new

• av hooks install deploys PATH-level wrappers around crontab and systemctl --user. After install, open a new terminal and any mutation is refused unless a vitals call has been made in the last 60 seconds.
• Reads (crontab -l, systemctl status, etc.) always pass through. No friction.
• Power management (reboot, poweroff, suspend) explicitly NOT gated — a stale stamp must never block a reboot.
• Bypass for emergencies: VITALS_BYPASS=1 crontab -e.

Install

uv tool install --force --reinstall git+https://github.com/anirudhprashant/agent-vitals
av hooks install    # auto-appends PATH snippet to ~/.bashrc and ~/.zshrc
                    # open a new terminal

That's the whole setup. From now on:

$ crontab -e
  ⚡ agent-vitals hook: refused `crontab -e`

  reason:   vitals stamp is 5m12s old — exceeds 60s window.
  stamp:    5m12s ago

  refresh:  call any vitals tool or run `av doctor`
  bypass:   VITALS_BYPASS=1 crontab -e

Tests

104 unit tests covering:

• Mutation detection for every crontab and systemctl arg combo (reads, mutations, bundled shorts, bundled -u, value-flags, power-mgmt carve-out)
• Stamp behavior (touch, read, age, bypass, window, missing file)
• Gate end-to-end with mocked real-binary

$ uv run python -m unittest tests.test_stamp tests.test_hooks
Ran 104 tests in 0.038s
OK

Subprocess integration tests are skipped — they fail under uv run because of env-var interaction with Typer subcommand routing. Same logic is fully covered by unit tests.

Stack

~1200 LOC of Python + 104 tests. typer + rich + pyyaml + mcp. MIT.

Anti-patterns now blocked at the OS level

• ❌ Writing a crontab entry without verifying the target exists
• ❌ Enabling a systemd service without first checking infrastructure health
• ❌ Restarting services while 6 other sessions are already stuck
• ❌ Claiming "all cron is fine" without calling shadow_stale

Links

• Repo: https://github.com/anirudhprashant/agent-vitals
• Landing: https://anirudhprashant.github.io/agent-vitals/
• v0.2.1: previous release
• v0.1.0: original MVP

v0.2.1 — fix MCP dedupe

Small fix on top of v0.2.0:

• Stop deduping MCP servers across hosts. Multi-host setups (pi + Claude Code on the same box) correctly register the same MCP server in both configs — that's intentional, not a duplicate. v0.2.0's dedupe logic was flagging agent-vitals and mempalace as 'duplicate' just because they appear in both ~/.pi/agent/mcp.json and ~/.claude/.mcp.json. Removed. Each record still carries a 'from ' note so the user can see exactly where each registration lives.

Otherwise identical to v0.2.0.

v0.2.0 — agent-first: MCP server + av init

Big shift: agents, not users

v0.2.0 reframes agent-vitals as infrastructure for AI agents, not a CLI for humans. The MCP server is now the primary surface. Humans just verify it's wired up correctly.

New

• MCP server (av mcp) exposing 5 tools:
  • vitals_summary — plain-English health check. Always-call-first.
  • shadow_list — full list of scheduled/configured agents.
  • shadow_stale — only broken references.
  • burnout_summary — task completion metrics.
  • burnout_stuck_sessions — likely-stuck Claude Code sessions.
• av init — detects installed agent hosts (pi, Claude Code, Cursor, OpenCode, Codex CLI) and:
  1. Registers agent-vitals as an MCP server in each (JSON or TOML config).
  2. Installs a SKILL.md / rule snippet that primes the agent to call vitals proactively (before tasks, before scheduling, when stuck, after long tasks, when claiming something works).
• av doctor — health check with actionable recommendations.
• av detect — list detected hosts.
• --watch mode on shadow/burnout for live refresh.
• README rewritten with the agent-first narrative + trigger table.

Install + wire up

uv tool install git+https://github.com/anirudhprashant/agent-vitals
av init     # auto-wires pi / Claude Code / OpenCode / Cursor / Codex CLI

Restart your agent host. Done.

Stack

Python 3.11+, uv-managed. typer + rich + pyyaml + mcp. ~900 LOC of Python + the priming SKILL.md.

Anti-patterns this version exists to prevent

❌ Agent claims 'your crontab is fine' without calling shadow_stale
❌ Agent schedules cron work without verifying the target exists
❌ Agent starts a 4-hour task while 6 other sessions are stuck
❌ Agent pretends a task completed without checking burnout_summary
❌ Agent recommends an MCP server install without checking for duplicates

License

MIT.

v0.1.0 — initial MVP

First public release.

What's in this release

Two CLI commands for solo-dev AI agent observability:

• shadow — enumerate everything scheduled/configured to act on your behalf (cron, systemd user timers, MCP server configs across pi/Claude/Cursor, agent skill frontmatter with schedule triggers). Detects stale cron targets, dedupes MCP servers across configs and tags duplicates.
• burnout — task completion/abandonment metrics from pi subagent run-history.jsonl and Claude Code session JSONL. Flags sessions with 200+ events as likely stuck loops.

Install

uv tool install git+https://github.com/anirudhprashant/agent-vitals

Stack

Python 3.11+, uv-managed, typer + rich + pyyaml. ~560 LOC. MIT.