agent-stalker

Agent Stalker

Real-time observability for Claude Code agent teams. Track sessions, tool use, task lifecycle, and inter-agent messaging through a live web dashboard and CLI query engine.

What It Does

Agent Stalker is a purely observational Claude Code plugin. It hooks into Claude's event system to record what agents do — without ever modifying or injecting into agent communication. Everything you see in the dashboard is a passive reflection of actual agent activity.

Track everything your agents do:

• Sessions — active, ended, and archived sessions with working directory context
• Tool use — every Read, Write, Bash, Edit, Grep, and custom tool call with inputs/outputs
• Agent teams — subagent spawns, stops, and per-agent activity timelines
• Task lifecycle — tasks flow through Pending → In Progress → Completed in a kanban board
• Inter-agent messaging — SendMessage calls between teammates

Screenshots

Live Dashboard

Full dashboard with kanban task board, agent/tool/event filter chips, and real-time activity feed. Each agent is color-coded for easy visual tracking.

Task Detail

Click any task card to see metadata, ownership, team assignment, and full event history showing every state transition.

Event Detail

Expand any activity event to see the raw tool input/output JSON data with syntax highlighting.

Installation

From the Hartye Plugins Marketplace (recommended)

Add the marketplace to your Claude Code settings, then install the plugin:

# Add the marketplace (one-time setup)
claude plugins add-marketplace ehartye/hartye-claude-plugins

# Install agent-stalker
claude plugins install agent-stalker

To update to the latest version:

claude plugins update

From Source (local development)

Clone the repo and register it as a local marketplace:

git clone https://github.com/ehartye/agent-stalker.git
cd agent-stalker
bun install

Add to your Claude Code settings (~/.claude/settings.json):

{
  "extraKnownMarketplaces": [
    {
      "name": "agent-stalker-dev",
      "source": "directory",
      "path": "/path/to/agent-stalker"
    }
  ]
}

Then install:

claude plugins install agent-stalker --marketplace agent-stalker-dev

Usage

Start the Dashboard

/stalker-ui

Opens the web dashboard at http://localhost:3141. Use --port <number> to change the port.

/stalker-ui stop

Stops the running dashboard server.

Query from the CLI

/stalker sessions              # List recent sessions
/stalker tools --session <id>  # Tool use frequency
/stalker events --since 1h     # Recent events
/stalker tasks --status pending # Filter tasks by status
/stalker agents                # List all spawned agents
/stalker stats                 # Summary statistics
/stalker tokens --by model     # Captured token usage

Count Tokens

/stalker-tokens --by session   # Real captured token usage (totals + breakdown)
/stalker-tokens --since 24h    # Usage in a recent window
/stalker-tokens count <file>   # Tokenize a file (exact with ANTHROPIC_API_KEY, else an estimate)

Real counts come from the usage table (parsed from transcripts on SessionEnd). Ad-hoc tokenization of arbitrary text/files is exact when ANTHROPIC_API_KEY is set (Anthropic's free count_tokens API), otherwise a clearly-labelled local estimate.

Note: the commands above are now skills (/stalker, /stalker-ui, /stalker-config, /stalker-tokens, /stalker-triage) — same invocation, plus contextual auto-triggering.

Configure Content Capture

/stalker-config             # Show current config
/stalker-config set Bash full       # Capture full Bash output
/stalker-config set Read metadata   # Metadata only for Read
/stalker-config reset               # Restore defaults

Default capture rules:

Tool	Rule
Edit, Write	metadata
Read, Glob, Grep	metadata
Bash	maxLength 2000
Everything else	maxLength 500

What is captured: events are stored in plaintext SQLite at ~/.claude/agent-stalker.db. By default file contents are not stored (metadata only); opt into full capture per-tool with /stalker-config set Edit full. The dashboard binds 127.0.0.1 — to view it from another machine, set "ui": { "host": "0.0.0.0" } in ~/.claude/agent-stalker.config.json. If browsing by machine name rather than IP, also add the name to "allowedHosts" (e.g. ["office-pc"]).

Dashboard Features