agent-watch

CLI tool for monitoring and browsing Claude Code sub-agent and session transcripts.

Core Features

Session & Agent Browsing

View and search through Claude Code session history and sub-agent transcripts. All views display rich metadata headers showing model, version, branch, project, timestamps, message count, and token usage breakdown. Auto-detects whether an ID is a session or agent.

Agent Orchestration (wait)

Block until one or more sub-agents complete. Essential for parallel agent workflows. Uses up to three detection methods:

1. Token log -- instant detection via hook-based completion entries
2. PID liveness -- checks if the Claude process is still running via kill -0
3. JSONL staleness -- fallback: no activity for 5 minutes = presumed complete

The PID hook is required for robust wait behavior. Without it, wait falls back to JSONL staleness, which will incorrectly presume an agent is dead if it's alive but idle for >5 minutes (e.g. long tool execution, slow model response). See the setup guide to configure hooks.

Interactive Mode

fzf-based selection with preview panels showing metadata and first exchanges. Browse sessions or agents, then view, watch live, or open full transcripts.

Pagination

Navigate large sessions without loading everything into memory. --limit sets a token budget (chars/4), --offset skips messages. Output includes NEXT_OFFSET=M for continuation.

Agent-Safe Commands

Non-interactive commands (list, list-sessions, view, session, wait) are safe for use by Claude Code agents themselves -- no TTY required.

Compaction & Hook Rendering

Sessions that hit context limits are compacted by Claude Code, which previously made the rest of the conversation invisible. agent-watch now renders these boundaries:

• [COMPACT] -- marks where compaction occurred (auto/manual, token count)
• [SUMMARY] -- the AI-generated summary injected after compaction (distinct from [USER])
• [HOOK] -- hook executions showing event, name, and script (e.g. SessionStart:startup → session-start.sh)

Both full compaction and in-place microcompaction are supported. Synthetic callback entries are filtered out.

Live Tailing

Stream agent output in real-time with colorized role markers ([USER], [ASST], [TOOL], [RESULT], [COMPACT], [HOOK], [SUMMARY]).

Installation

Dependencies

• bash 4+ (macOS ships bash 3 -- install via brew install bash)
• jq -- JSON parsing (brew install jq)
• fzf -- interactive selection and previews (brew install fzf), only needed for interactive mode
• bc -- token formatting (optional, usually pre-installed)

Install

curl -fsSL https://github.com/restot/agent-watch/releases/latest/download/agent-watch \
  -o ~/.local/bin/agent-watch && chmod +x ~/.local/bin/agent-watch

Verify it's in your PATH:

which agent-watch

If not found:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.$(basename "$SHELL")rc

Restart your shell or run exec $SHELL to apply.

Teach your agents

Append the agent-watch reference to your global Claude Code memory:

curl -fsSL https://raw.githubusercontent.com/restot/agent-watch/main/CLAUDE.md >> ~/.claude/CLAUDE.md

Usage

Usage: agent-watch [command] [args] [flags]

Non-interactive commands (safe for agents):
  list [count]        List recent sub-agents (default: 20)
    -p, --project <name>  Filter by project (case-insensitive partial match)
  list-sessions [n]   List all sessions (or last n)
    -p, --project <name>  Filter by project (case-insensitive partial match)
  view [id]           View agent transcript (most recent if no id)
  session <id>        View a specific session
  <id>                Auto-detect: view agent or session by ID
  wait <id> [id...]   Block until agent(s) complete
  update              Self-update to the latest release

Interactive commands (require TTY):
  (none)              fzf selection of sub-agents
  sessions [id]       fzf browser for sessions (or view specific session by ID)
  watch [id]          Live tail of agent output

All views display a metadata header:
  Model, Version, Branch, Project, Started/Ended, Messages, Tokens
  Sub-agents also show Slug; Permission shown when available.

Message markers:
  [USER]     User messages          [TOOL]     Tool calls (name + input)
  [ASST]     Assistant responses    [RESULT]   Tool results
  [COMPACT]  Compaction boundary    [SUMMARY]  Post-compaction summary
  [HOOK]     Hook execution         (callbacks are filtered out)

Pagination (for large sessions/agents):
  --limit N           Token budget (chars/4); prints NEXT_OFFSET=M when exceeded
  --offset N          Skip first N messages (combine with --limit to paginate)
  --last [N]          Show last message, or last N tokens (no header, no pager)

Other flags:
  --skip-tool-output  Show tool calls and args but hide tool result output
  --no-color          Disable colored output (also respects NO_COLOR env var)
  --debug             Show debug output
  --help              Show this help message
  --version           Show version number

Environment:
  NO_COLOR                    Disable colored output (see https://no-color.org/)
  AGENT_WATCH_STALE_TIMEOUT   Staleness threshold in seconds for wait fallback (default: 300)

Examples

Non-interactive (safe for agents)

List the 10 most recent sub-agents:

agent-watch list 10

View the most recent agent transcript:

agent-watch view

View a specific session or agent by ID (auto-detected):

agent-watch abc123de

Filter agents or sessions by project name:

agent-watch list -p my-project
agent-watch list-sessions -p my-project

Paginate through a large session:

agent-watch session abc123de --limit 5000
# Output includes NEXT_OFFSET=M if truncated
agent-watch session abc123de --offset 50 --limit 5000

Show the last 5000 tokens of a session (chronological order):

agent-watch abc123de --last 5000

View agent decision flow without tool result noise:

agent-watch abc123de --skip-tool-output --limit 5000

Disable colors (useful when calling from agents to save tokens):

NO_COLOR=1 agent-watch view
# or
agent-watch --no-color view

Wait for sub-agents to finish before continuing:

agent-watch wait abc123 def456

Interactive (require TTY)

Browse sessions with fzf:

agent-watch sessions

Browse sub-agents with fzf:

agent-watch

Live tail an active sub-agent:

agent-watch watch

How it works

Architecture and internals

File structure

~/.claude/projects/
  <project>/
    <session-id>.jsonl          <-- main session transcripts
    sessions-index.json         <-- session metadata (prompts, dates)
    subagents/
      agent-<id>.jsonl          <-- sub-agent transcripts

~/.claude/.agent-pids/          <-- PID files (optional, via hooks)
~/.claude/subagent-tokens.log   <-- token log (optional, via hooks)

Flow

Details

agent-watch reads Claude Code's JSONL session and agent files from ~/.claude/projects/. It parses metadata from the first few entries in each file (model, version, branch, timestamps) and aggregates token usage across all assistant entries.

JSON parsing is handled by jq. Interactive selection uses fzf with preview windows that show session metadata and recent messages. Output is colorized with role-based markers ([USER], [ASST], [TOOL], [RESULT], [COMPACT], [HOOK], [SUMMARY]) for readability. Color can be disabled via NO_COLOR=1 or --no-color to reduce token overhead when output is consumed by agents.

Compaction boundaries (compact_boundary, microcompact_boundary) and hook progress entries (hook_progress, stop_hook_summary) are parsed from the JSONL and rendered inline. Synthetic callback entries are filtered out to reduce noise.

Wiki

See the wiki for guides and screenshots:

• UI Overview -- screenshots of interactive session browsing, agent history, transcript view, and pagination
• Token Log & PID Tracking -- Claude Code hooks for faster wait detection and token usage logging

Contributing

1. Fork the repo
2. Create a branch (git checkout -b my-feature)
3. Edit source modules in cli/
4. Build: ./build.sh (assembles bin/agent-watch, runs syntax check)
5. Run tests: make test (or make docker-test to run in Docker)
6. Submit a PR

Source modules live in cli/, assembled by build.sh into bin/agent-watch. The root agent-watch is the legacy monolith kept for backwards compatibility.

CI runs on both Ubuntu and macOS to catch GNU/BSD differences. Quick syntax + unit check: make check.

Docker

Run tests and coverage analysis in Docker without installing dependencies locally:

make docker-test       # Run all tests
make docker-coverage   # Run coverage, copies badge + HTML report to project root

License

MIT