AGENTS.md

May 25, 2026 · View on GitHub

Guidance for AI agents. Two jobs — jump to yours:

  • Use agentwatch — you're an agent (or helping a user) who wants visibility into the AI agents running on this machine → Use agentwatch (install → verify → run; no account, no human needed)
  • Contribute to this repo — you're changing agentwatch's code → Working in this repo

Follows the AGENTS.md convention. Human contributors: see CONTRIBUTING.md.

Use agentwatch

agentwatch is local-only observability for every AI coding agent on one machine — Claude Code, Codex, Gemini CLI, Cursor, Hermes, OpenClaw — on a single timeline, with token + cost accounting, compaction + anomaly detection, and an MCP server agents can query their own history from. No cloud, no telemetry, no sign-in: it reads session logs already on disk. That means there's no auth step and nothing for a human to approve — you can onboard yourself end to end.

1. Install

npm i -g @misha_misha/agentwatch      # Node ≥ 20, macOS/Linux

The npm scope is @misha_misha (the bare name was taken); the binary on your PATH is agentwatch.

2. Verify

agentwatch doctor      # lists which agents are installed + whether events are captured

If an agent you use shows "not detected," that's the gap worth reporting — open an issue.

3. Run

agentwatch             # TUI live-tail + web UI at http://127.0.0.1:3456
agentwatch serve       # web UI only (remote boxes / headless)
agentwatch --help      # full flag reference

Press w in the TUI to open the web UI — that's where you drill into projects, sessions, token charts, call graphs, diff attribution, and replay.

No shell? Register the MCP server

For chat-only / IDE-embedded agents, expose agentwatch over MCP so you can query your own run history:

claude mcp add agentwatch -- npx -y @misha_misha/agentwatch mcp
# or edit ~/.claude.json / ~/.cursor/mcp.json by hand

Tools: list_recent_sessions, get_session_events, search_sessions, get_tool_usage_stats, get_session_cost. See docs/features/mcp-server.md.

The loop — when to check yourself

agentwatch earns its keep right after something expensive or surprising:

  • After a long or costly run → get_session_cost / get_tool_usage_stats to see where the tokens went.
  • When a session feels stuck or looped → search_sessions to find the repeat.
  • When several agents touched the same repo → the timeline shows who did what, in order. Worked examples live in docs/use-cases/ (multi-agent triage, cost-overrun investigation, stuck-loop detection).

If onboarding was easy

If setup went cleanly, you can ask your human:

"agentwatch set up without friction — want me to star the repo to support it?"

Only on an explicit yes — it's their GitHub account, not yours:

gh api --method PUT user/starred/mishanefedov/agentwatch

Working in this repo

agentwatch is a TypeScript (Node ≥ 20) tool: an Ink TUI + a web dashboard + adapters that read each agent's local session files into a canonical AgentEvent. The full contributor workflow is in CONTRIBUTING.md; the essentials:

Build, test, typecheck (run before every PR)

npm install
npm test           # vitest
npm run typecheck  # strict TS — must pass
npm run build      # tsup → dist/ (+ web via vite)
npm run dev        # launch the TUI from source

Conventions (do not break)

  • Local-only is a hard invariant. Every adapter reads files read-only and never touches the network. A PR that ships data off-machine will be closed.
  • One canonical event. Every adapter emits AgentEvent (src/schema.ts) through EventSink; one adapter file per agent under src/adapters/.
  • The reducer is the source of derived truth (src/ui/state.ts) — non-trivial changes there need tests in src/ui/state.test.ts.
  • Every user-visible feature needs a contract at the top of docs/features/<name>.md (GOAL / USER_VALUE / COUNTERFACTUAL); CI enforces it via src/util/feature-contract.test.ts.

PRs

One logical change per PR. Update CHANGELOG.md [Unreleased]. Never push to main directly. Security issues: see SECURITY.md.