Session Monitor

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

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)

| Variable | Required | Description | |----------|----------|-------------| | BOT_TOKEN | ✅ | Telegram bot token for sending updates | | CHAT_ID | ✅ | Target Telegram chat ID (group or DM) | | AGENTS | ❌ | Multi-agent: Name\|/path/to/sessions,Name2\|/path2 | | AGENT_NAME | ❌ | Single-agent display name (fallback when AGENTS unset) | | SESSIONS_DIR | ❌ | Single-agent session dir (default: ~/.openclaw/agents/main/sessions) | | DIRECT_USERS | ❌ | Direct chat mappings: userId:Name,userId2:Name2 | | GROUPS | ❌ | Group chat mappings: groupId:Name,groupId2:Name2 |

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:

Message Format

See references/REFERENCE.md for detailed format specification including:

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

# 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