Session Monitor

Persistent background process that polls all JSONL transcript files in an
agent's session directory, parses new entries, and pushes formatted HTML
updates to a Telegram chat. Messages within the same time window are merged
via editMessageText to avoid spam.

When to Use

• User wants continuous, push-based monitoring of agent activity
• User wants a live dashboard in a Telegram chat showing what the agent does
• NOT for one-shot queries — use sessions_list / sessions_history instead

Quick Start

# 1. Configure
cp scripts/.env.example scripts/.env
# Edit scripts/.env with bot token, chat ID, session dir, user/group mappings

# 2. Dry-run (verify parsing works)
node scripts/test.js

# 3. Start (exec session safe — won't die when agent session ends)
node scripts/index.js > scripts/monitor.log 2>&1 &

⚠️ Agent exec sessions: Processes started via nohup & inside an
agent's exec tool may be killed when the exec session is cleaned up.
Add a watchdog to your HEARTBEAT.md to auto-restart:

PID=$(cat scripts/.pid 2>/dev/null)
if [ -z "$PID" ] || ! ps -p "$PID" > /dev/null 2>&1; then
  cd scripts && node index.js > monitor.log 2>&1 &
fi

Configuration (.env)

Display format: direct chats show as ✈ AgentName↔UserName, groups as ✈ GroupName.

Architecture

scripts/
├── index.js      — Main loop: poll JSONL, accumulate, send/edit Telegram messages
├── parser.js     — Parse JSONL entries into {sender, text} display objects
├── formatter.js  — Merge same-sender messages, sort sessions, build HTML
├── sender.js     — Telegram API: sendMessage / editMessageText with queue
├── sessions.js   — Session key lookup, tag formatting, subagent name resolution
├── config.js     — Load .env configuration
├── test.js       — Dry-run: parse recent entries and print to stdout
├── .env.example  — Configuration template
└── .env          — Local config (gitignored)

Tuning

In scripts/index.js:
- POLL = 3000 — Poll interval in ms (default 3s)
- MERGE_WINDOW = 1 — Merge edits within N minutes into one Telegram message
- NEW_MSG_THRESHOLD = 3000 — Start a new message when current exceeds this many chars

Message Format

See references/REFERENCE.md for detailed format specification including:
- Sender icons (🤖 assistant, 👤 user, ⚡ system, ↩️ tool result)
- Tool call formatting and truncation rules
- Session tag formatting and sort order
- Telegram delivery and rate limiting

Management

PID file at scripts/.pid is written on startup, cleaned on exit.
Always use the full path to avoid cross-monitor conflicts on shared machines:

# Check if running
SKILL_DIR=/path/to/session-monitor
cat "$SKILL_DIR/scripts/.pid" && ps -p $(cat "$SKILL_DIR/scripts/.pid") -o pid,command

# Stop
kill $(cat "$SKILL_DIR/scripts/.pid")

# View logs
tail -f "$SKILL_DIR/scripts/monitor.log"

⚠️ Multiple monitors may coexist on the same machine (each with its own
.env, .pid, and log). Always reference the correct skill directory.

Restart / Stop / Status

Resolve SKILL_DIR to this skill's directory (parent of scripts/).

# Status — is monitor running?
SKILL_DIR=/absolute/path/to/session-monitor
PID=$(cat "$SKILL_DIR/scripts/.pid" 2>/dev/null)
if [ -n "$PID" ] && ps -p "$PID" > /dev/null 2>&1; then
  echo "✅ Monitor running (PID $PID)"
else
  echo "❌ Monitor not running"
fi

# Stop
kill $(cat "$SKILL_DIR/scripts/.pid")

# Start
cd "$SKILL_DIR/scripts" && node index.js > monitor.log 2>&1 &

# Restart (stop + start)
kill $(cat "$SKILL_DIR/scripts/.pid") 2>/dev/null; sleep 1
cd "$SKILL_DIR/scripts" && node index.js > monitor.log 2>&1 &

Notes

• Zero dependencies — pure Node.js standard library
• Startup sends a sample banner message to verify connectivity
• Messages > 4000 chars are truncated and force a new message next poll
• Rate limit: 3s gap between Telegram API calls