convez.ai
Agente
ehartye

agent-stalker

ehartye/agent-stalker

Ver no GitHub
InicialPluginScore · de 0 a 100

Claude Code plugin that tracks agent team task assignment, messages, and tool use across sessions into SQLite

Instalação

$npx convez-ai ehartye/agent-stalker

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Agent Stalker Hero

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.

Dashboard

Task Detail

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

Task Detail

Event Detail

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

Event Detail

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:

ToolRule
Edit, Writemetadata
Read, Glob, Grepmetadata
BashmaxLength 2000
Everything elsemaxLength 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

  • Session selector — pick one or more sessions to view simultaneously; search by name
  • Kanban board — tasks organized by status (Pending / In Progress / Completed) with owner badges
  • Filter chips — filter by agent, tool name, or event type; click to toggle, counts update live
  • Activity feed — chronological event stream with color-coded agent labels; click to expand JSON detail
  • Task modals — click any task card for full metadata and event history
  • Live mode — auto-polls for new events; handles browser tab throttling with visibility-change detection
  • Search — filter events by text across tool names, file paths, and commands
  • Stats footer — session count, total events, unique tools, agents, and tasks at a glance

Insights / meta-analysis

The Insights view (toggle in the dashboard header, next to Activity) surfaces pockets of high thrash, churn, error, and token usage across your agentic workflows. It has two layers.

Every Insights table is sortable (click a column header) and every row drills in — sessions open in the Activity view, single prompts/tasks open a detail modal, and aggregate rows (a file, tool, error cluster, topic, or retry chain) open a list of their underlying events.

Structured metrics (always on)

Computed directly from the captured events — no extra setup, no external services:

  • Pain leaderboard — a per-session composite score combining error rate, file churn, thrash, and effort, each normalized and weighted; every row shows an explainable breakdown so you can see why a session scored high.
  • Token usage — real input/output/cache token totals per session (populated by the usage ingest; see below).
  • File churn — files edited most often, with edit counts, the sessions touching them, and the median gap between edits.
  • Errors — error counts by tool and by session (with error rate).
  • Thrash / pivot-loops — error→retry chains on the same tool+target, and task status "bounces" (re-entering a status the task was already in).

Token usage capture: real token counts come from the Claude Code transcript JSONL files, parsed into a usage table. This runs automatically on SessionEnd, or on demand:

bun run ingest-usage

Until a session's transcript has been ingested, the effort signal falls back to a byte-based proxy.

Semantic sidecar (opt-in)

An optional Python layer adds NLP-based insight: frustration/sentiment, topic modeling, error clustering, and semantic pivot detection. It is opt-in and runs as a separate batch process that reads the same SQLite database and writes semantic_* tables; the dashboard hides these panels until they contain data. (Session triage is not part of this sidecar — it needs no API key and runs in Claude Code; see below.)

To enable it, install the Python dependencies once:

pip install -r analysis/requirements.txt

Then click Enable semantic features in the Insights view (or run python -m agent_stalker_analysis run from analysis/). After it completes, refresh to see the Topics, Error clusters, Frustration, and Agent pivots panels populate.

Session triage (no API key): each pain-leaderboard row has a Flag for triage button. Clicking it marks the session in the database; then run the packaged /stalker-triage skill in Claude Code, which reads the flagged sessions, scores each one's workflow pain, and writes a summary + root cause back so the dashboard's Triage panel shows them. No Anthropic API key and no token cost — the analysis runs in the Claude Code session you're already using.

See analysis/README.md for the full sidecar install/run guide, the SQLite contract, and environment variables.

Architecture

hooks/tracker.ts          # Hook entrypoint — receives events via stdin
lib/ingest.ts             # Parses hook payloads, writes to SQLite
lib/db.ts                 # Database schema + migrations (v1-v7)
lib/query.ts              # CLI query engine
lib/config.ts             # Content capture configuration
lib/truncate.ts           # Content truncation per capture rules
lib/resolve-team.ts       # Team/agent resolution logic
ui/server.ts              # Bun HTTP server — REST API + static files
ui/app.js                 # Single-file dashboard UI (vanilla JS)
ui/index.html             # Dashboard HTML shell
ui/style.css              # Dark theme styles
commands/                 # Slash command definitions
.claude-plugin/plugin.json # Plugin manifest
hooks/hooks.json          # Hook event registrations

All hooks run asynchronously via bun and write to a shared SQLite database at ~/.claude/agent-stalker.db (WAL mode for concurrent access). The web UI reads from the same database via a lightweight REST API.

Tracked Hook Events

EventWhat's Captured
SessionStart / SessionEndSession lifecycle, CWD, model, permissions
PreToolUse / PostToolUseTool name, inputs, outputs (per capture rules)
SubagentStart / SubagentStopAgent spawn/stop with type and transcript path
TaskCompletedTask completion with subject and owner
TeammateIdleIdle agent detection
UserPromptSubmitUser prompt submissions
StopSession stop events

Requirements

  • Bun runtime (used by hooks and the dashboard server)
  • Claude Code with plugin support

License

MIT

Ver o original no GitHub

Bom para

Relacionados