Agent skill

Agent Session Monitor

by higress-group in higress-group/higress

Real-time agent conversation monitoring - monitors Higress access logs, aggregates conversations by session, tracks token usage.

Apache-2.0Auto-check passedData & Analytics

Install Agent Session Monitor

skills CLI
$ npx skills add higress-group/higress --skill agent-session-monitor -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install higress-group/higress agent-session-monitor --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/higress-group/higress.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/agent-session-monitor .claude/skills/agent-session-monitor && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
agent-session-monitor
GitHub stars
9.5k
Token cost
~3.3k tokens
SKILL.md length
714 words
Files
12 (incl. scripts)
Skills in repo
11
Repo updated
First seen
Licence
Apache-2.0

At a glance

Real-time agent conversation monitoring - monitors Higress access logs, aggregates conversations by session, tracks token usage.

  • Works in 9 steps: Background Monitoring (Continuous) → Start Web UI (Recommended) → Use in Clawdbot Conversations → …
  • Users ask about current session token consumption
  • SKILL.md covers Overview, Usage, Configuration and Output Examples, plus 3 more sections
  • Runs Python and Shell scripts from its folder; calls python3

What it does

Agent Session Monitor is an agent skill from higress-group/higress. Real-time agent conversation monitoring - monitors Higress access logs, aggregates conversations by session, tracks token usage. Supports web interface for viewing complete conversation history and costs. Use when users ask about current session token consumption, conversation history, or cost statistics.

Its SKILL.md is about 3.3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 13 other files, including scripts (for example `QUICKSTART.md`, `README.md` and `example/clawdbot_demo.py`).

It sits in Data & Analytics, covering Frontend development and Statistics. The repository describes itself as: 🤖 AI Gateway | AI Native API Gateway. The licence is Apache-2.0.

When your agent uses it

  • Users ask about current session token consumption
  • Conversation history
  • Cost statistics

Example prompts

  • “/agent-session-monitor”

Requirements

  • Python 3
  • A Bash shell

Workflow steps

9 steps, taken from the step headings in SKILL.md.

  1. Background Monitoring (Continuous)
  2. Start Web UI (Recommended)
  3. Use in Clawdbot Conversations
  4. CLI Queries (Optional)
  5. Real-time Monitor
  6. CLI Session Details
  7. Statistics by Model
  8. Statistics by Date
  9. Web UI (Recommended)

What it can do on your machine

Read from SKILL.md and the folder at commit c74d7e2. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 2 files in scripts/ (Python and Shell), which the agent can run.

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Agent Session Monitor loads about 3.3k tokens when it runs. Until then it costs about 82 tokens; SKILL.md has 714 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~82
When it runs · the whole SKILL.md, loaded when a task matches
~3.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from higress-group/higress at commit c74d7e2, republished under its Apache-2.0 licence (© higress-group). 714 words, ~3,293 tokens.

Download SKILL.mdSave it as .claude/skills/agent-session-monitor/SKILL.md (or your agent's skills folder). This skill also uses 11 other files; get the full folder from GitHub.
name
agent-session-monitor
description
Real-time agent conversation monitoring - monitors Higress access logs, aggregates conversations by session, tracks token usage. Supports web interface for viewing complete conversation history and costs. Use when users ask about current session token consumption, conversation history, or cost statistics.

Overview

Real-time monitoring of Higress access logs, extracting ai_log JSON, grouping multi-turn conversations by session_id, and calculating token costs with visualization.

Core Features
  • Real-time Log Monitoring: Monitors Higress access log files, parses new ai_log entries in real-time
  • Log Rotation Support: Full logrotate support, automatically tracks access.log.1~5 etc.
  • Incremental Parsing: Inode-based tracking, processes only new content, no duplicates
  • Session Grouping: Associates multi-turn conversations by session_id (each turn is a separate request)
  • Complete Conversation Tracking: Records messages, question, answer, reasoning, tool_calls for each turn
  • Token Usage Tracking: Distinguishes input/output/reasoning/cached tokens
  • Web Visualization: Browser-based UI with overview and session drill-down
  • Real-time URL Generation: Clawdbot can generate observation links based on current session ID
  • Background Processing: Independent process, continuously parses access logs
  • State Persistence: Maintains parsing progress and session data across runs

Usage

1. Background Monitoring (Continuous)
bash
# Parse Higress access logs (with log rotation support)
python3 main.py --log-path /var/log/proxy/access.log --output-dir ./sessions

# Filter by session key
python3 main.py --log-path /var/log/proxy/access.log --session-key <session-id>

# Scheduled task (incremental parsing every minute)
* * * * * python3 /path/to/main.py --log-path /var/log/proxy/access.log --output-dir /var/lib/sessions
bash
# Start web server
python3 scripts/webserver.py --data-dir ./sessions --port 8888

# Access in browser
open http://localhost:8888

Web UI features:

  • 📊 Overview: View all session statistics and group by model
  • 🔍 Session Details: Click session ID to drill down into complete conversation history
  • 💬 Conversation Log: Display messages, question, answer, reasoning, tool_calls for each turn
  • 💰 Cost Statistics: Real-time token usage and cost calculation
  • 🔄 Auto Refresh: Updates every 30 seconds
3. Use in Clawdbot Conversations

When users ask about current session token consumption or conversation history:

  1. Get current session_id (from runtime or context)
  2. Generate web UI URL and return to user

Example response:

Your current session statistics:
- Session ID: agent:main:discord:channel:1465367993012981988
- View details: http://localhost:8888/session?id=agent:main:discord:channel:1465367993012981988

Click the link to see:
✅ Complete conversation history
✅ Token usage breakdown per turn
✅ Tool call records
✅ Cost statistics
4. CLI Queries (Optional)
bash
# View specific session details
python3 scripts/cli.py show <session-id>

# List all sessions
python3 scripts/cli.py list --sort-by cost --limit 10

# Statistics by model
python3 scripts/cli.py stats-model

# Statistics by date (last 7 days)
python3 scripts/cli.py stats-date --days 7

# Export reports
python3 scripts/cli.py export finops-report.json

Configuration

main.py (Background Monitor)
ParameterDescriptionRequiredDefault
--log-pathHigress access log file pathYes/var/log/higress/access.log
--output-dirSession data storage directoryNo./sessions
--session-keyMonitor only specified session keyNoMonitor all sessions
--state-fileState file path (records read offsets)No<output-dir>/.state.json
--refresh-intervalLog refresh interval (seconds)No1
webserver.py (Web UI)
ParameterDescriptionRequiredDefault
--data-dirSession data directoryNo./sessions
--portHTTP server portNo8888
--hostHTTP server addressNo0.0.0.0

Output Examples

1. Real-time Monitor
🔍 Session Monitor - Active
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Active Sessions: 3

┌──────────────────────────┬─────────┬──────────┬───────────┐
│ Session ID               │ Msgs    │ Input    │ Output    │
├──────────────────────────┼─────────┼──────────┼───────────┤
│ sess_abc123              │       5 │    1,250 │       800 │
│ sess_xyz789              │       3 │      890 │       650 │
│ sess_def456              │       8 │    2,100 │     1,200 │
└──────────────────────────┴─────────┴──────────┴───────────┘

📈 Token Statistics
  Total Input:   4240 tokens
  Total Output:  2650 tokens
  Total Cached:  0 tokens
  Total Cost:    $0.00127
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2. CLI Session Details
bash
$ python3 scripts/cli.py show agent:main:discord:channel:1465367993012981988

======================================================================
📊 Session Detail: agent:main:discord:channel:1465367993012981988
======================================================================

🕐 Created:  2026-02-01T09:30:00+08:00
🕑 Updated:  2026-02-01T10:35:12+08:00
🤖 Model:    Qwen3-rerank
💬 Messages: 5

📈 Token Statistics:
   Input:           1,250 tokens
   Output:            800 tokens
   Reasoning:         150 tokens
   Total:           2,200 tokens

💰 Estimated Cost: $0.00126000 USD

📝 Conversation Rounds (5):
──────────────────────────────────────────────────────────────────────

  Round 1 @ 2026-02-01T09:30:15+08:00
    Tokens: 250 in → 160 out
    🔧 Tool calls: Yes
    Messages (2):
      [user] Check Beijing weather
    ❓ Question: Check Beijing weather
    ✅ Answer: Checking Beijing weather for you...
    🧠 Reasoning: User wants to know Beijing weather, I need to call weather API.
    🛠️  Tool Calls:
       - get_weather({"location":"Beijing"})
3. Statistics by Model
bash
$ python3 scripts/cli.py stats-model

================================================================================
📊 Statistics by Model
================================================================================

Model                Sessions   Input           Output          Cost (USD)  
────────────────────────────────────────────────────────────────────────────
Qwen3-rerank         12         15,230          9,840           $  0.016800
DeepSeek-R1          5          8,450           6,200           $  0.010600
Qwen-Max             3          4,200           3,100           $  0.008300
GPT-4                2          2,100           1,800           $  0.017100
────────────────────────────────────────────────────────────────────────────
TOTAL                22         29,980          20,940          $  0.052800

================================================================================
4. Statistics by Date
bash
$ python3 scripts/cli.py stats-date --days 7

================================================================================
📊 Statistics by Date (Last 7 days)
================================================================================

Date         Sessions   Input           Output          Cost (USD)   Models              
────────────────────────────────────────────────────────────────────────────
2026-01-26   3          2,100           1,450           $  0.0042   Qwen3-rerank
2026-01-27   5          4,850           3,200           $  0.0096   Qwen3-rerank, GPT-4
2026-01-28   4          3,600           2,800           $  0.0078   DeepSeek-R1, Qwen
────────────────────────────────────────────────────────────────────────────
TOTAL        22         29,980          20,940          $  0.0528

================================================================================

Access http://localhost:8888 to see:

Home Page:

  • 📊 Total sessions, token consumption, cost cards
  • 📋 Recent sessions list (clickable for details)
  • 📈 Statistics by model table

Session Detail Page:

  • 💬 Complete conversation log (messages, question, answer, reasoning, tool_calls per turn)
  • 🔧 Tool call history
  • 💰 Token usage breakdown and costs

Features:

  • 🔄 Auto-refresh every 30 seconds
  • 📱 Responsive design, mobile-friendly
  • 🎨 Clean UI, easy to read

Session Data Structure

Each session is stored as an independent JSON file with complete conversation history and token statistics:

json
{
  "session_id": "agent:main:discord:channel:1465367993012981988",
  "created_at": "2026-02-01T10:30:00Z",
  "updated_at": "2026-02-01T10:35:12Z",
  "messages_count": 5,
  "total_input_tokens": 1250,
  "total_output_tokens": 800,
  "total_reasoning_tokens": 150,
  "total_cached_tokens": 0,
  "model": "Qwen3-rerank",
  "rounds": [
    {
      "round": 1,
      "timestamp": "2026-02-01T10:30:15Z",
      "input_tokens": 250,
      "output_tokens": 160,
      "reasoning_tokens": 0,
      "cached_tokens": 0,
      "model": "Qwen3-rerank",
      "has_tool_calls": true,
      "response_type": "normal",
      "messages": [
        {
          "role": "system",
          "content": "You are a helpful assistant..."
        },
        {
          "role": "user",
          "content": "Check Beijing weather"
        }
      ],
      "question": "Check Beijing weather",
      "answer": "Checking Beijing weather for you...",
      "reasoning": "User wants to know Beijing weather, need to call weather API.",
      "tool_calls": [
        {
          "index": 0,
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\":\"Beijing\"}"
          }
        }
      ],
      "input_token_details": {"cached_tokens": 0},
      "output_token_details": {}
    }
  ]
}
Show full SKILL.md (318 more words)Show less
Field Descriptions

Session Level:

  • session_id: Unique session identifier (from ai_log's session_id field)
  • created_at: Session creation time
  • updated_at: Last update time
  • messages_count: Number of conversation turns
  • total_input_tokens: Cumulative input tokens
  • total_output_tokens: Cumulative output tokens
  • total_reasoning_tokens: Cumulative reasoning tokens (DeepSeek, o1, etc.)
  • total_cached_tokens: Cumulative cached tokens (prompt caching)
  • model: Current model in use

Round Level (rounds):

  • round: Turn number
  • timestamp: Current turn timestamp
  • input_tokens: Input tokens for this turn
  • output_tokens: Output tokens for this turn
  • reasoning_tokens: Reasoning tokens (o1, etc.)
  • cached_tokens: Cached tokens (prompt caching)
  • model: Model used for this turn
  • has_tool_calls: Whether includes tool calls
  • response_type: Response type (normal/error, etc.)
  • messages: Complete conversation history (OpenAI messages format)
  • question: User's question for this turn (last user message)
  • answer: AI's answer for this turn
  • reasoning: AI's thinking process (if model supports)
  • tool_calls: Tool call list (if any)
  • input_token_details: Complete input token details (JSON)
  • output_token_details: Complete output token details (JSON)

Log Format Requirements

Higress access logs must include ai_log field (JSON format). Example:

json
{
  "__file_offset__": "1000",
  "timestamp": "2026-02-01T09:30:15Z",
  "ai_log": "{\"session_id\":\"sess_abc\",\"messages\":[...],\"question\":\"...\",\"answer\":\"...\",\"input_token\":250,\"output_token\":160,\"model\":\"Qwen3-rerank\"}"
}

Supported ai_log attributes:

  • session_id: Session identifier (required)
  • messages: Complete conversation history
  • question: Question for current turn
  • answer: AI answer
  • reasoning: Thinking process (DeepSeek, o1, etc.)
  • reasoning_tokens: Reasoning token count (from PR #3424)
  • cached_tokens: Cached token count (from PR #3424)
  • tool_calls: Tool call list
  • input_token: Input token count
  • output_token: Output token count
  • input_token_details: Complete input token details (JSON)
  • output_token_details: Complete output token details (JSON)
  • model: Model name
  • response_type: Response type

Implementation

Technology Stack
  • Log Parsing: Direct JSON parsing, no regex needed
  • File Monitoring: Polling-based (no watchdog dependency)
  • Session Management: In-memory + disk hybrid storage
  • Token Calculation: Model-specific pricing for GPT-4, Qwen, Claude, o1, etc.
Privacy and Security
  • ✅ Does not record conversation content in logs, only token statistics
  • ✅ Session data stored locally, not uploaded to external services
  • ✅ Supports log file path allowlist
  • ✅ Session key access control
Performance Optimization
  • Incremental log parsing, avoids full scans
  • In-memory session data with periodic persistence
  • Optimized log file reading (offset tracking)
  • Inode-based file identification (handles rotation efficiently)

© higress-group, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 11 other files (scripts) in .agents/skills/agent-session-monitor of higress-group/higress.

  • SKILL.md
  • QUICKSTART.md
  • README.md
  • example/clawdbot_demo.py
  • example/demo.sh
  • example/demo_v2.sh
  • example/test_access.log
  • example/test_access_v2.log
  • example/test_rotation.sh
  • main.py
  • scripts/cli.py
  • scripts/webserver.py

Open the folder on GitHubat commit c74d7e2

Compare with similar skills

Agent Session Monitor next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Agent Session Monitor compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Agent Session Monitor this skillhigress-group/higress9.5k—~3.3kAutomated safety check: PassApache-2.0
Statisticsthedaviddias/ux-patterns-for-developers259—~1kAutomated safety check: PassCustom licence
Sandbox Benchvercel/next.js143k—~4.1kAutomated safety check: PassMIT
Statistical Analysisspacering-net/codeg3.9k3 repos~5kAutomated safety check: PassMIT
StatsmodelszLanqing/codex-claude-academic-skills4.7k15 repos~4.9kAutomated safety check: PassBSD-3-Clause
AI Daily DigestvigorX777/ai-daily-digest1.6k—~1.3kAutomated safety check: PassNone

Similar skills

  • Statistics

    thedaviddias/ux-patterns-for-developers

    A skill your agent uses when you need to display key metrics and statistics.

    259 GitHub stars~1k tokensUpdated 6 days ago
    Data & AnalyticsAuto-check passed
  • Sandbox Bench

    vercel/next.js

    Official

    Benchmark React or Next.js changes on Vercel Sandbox VMs with paired A/B statistics: react PR/commit vs base, or Next.js PR/commit vs base, measured end-to-end through the bench/render-pipeline app…

    143k GitHub stars~4.1k tokensUpdated today
    Data & AnalyticsAuto-check passed
  • Statistical Analysis

    spacering-net/codeg

    Guided statistical analysis for research data - test selection, assumption checking, effect sizes, power analysis, Bayesian alternatives, and APA-formatted reporting.

    3.9k GitHub starsUsed in 3 repos~5k tokens
    Data & AnalyticsAuto-check passed
  • Statsmodels

    zLanqing/codex-claude-academic-skills

    Statistical models library for Python. An agent skill from zLanqing/codex-claude-academic-skills.

    4.7k GitHub starsUsed in 15 repos~4.9k tokens
    Data & AnalyticsAuto-check passed
  • AI Daily Digest

    vigorX777/ai-daily-digest

    Fetches RSS feeds from 90 top Hacker News blogs (curated by Karpathy), uses AI to score and filter articles, and generates a daily digest in Markdown with Chinese-translated titles, category…

    1.6k GitHub stars~1.3k tokensUpdated 7 mo ago
    Data & AnalyticsAuto-check passed
  • Statistical Power

    spacering-net/codeg

    Sample-size and statistical power calculations for planning studies.

    3.9k GitHub starsUsed in 1 repo~3.6k tokens
    Data & AnalyticsAuto-check: notes

More from higress-group/higress

All 11 skills in this repo
  • Higress Openclaw Integration

    higress-group/higress

    Deploy and configure Higress AI Gateway for OpenClaw integration.

    9.5k GitHub stars~2.5k tokensUpdated 3 days ago
    Auto-check passed
  • Nginx To Higress Migration

    higress-group/higress

    Migrate from ingress-nginx to Higress in Kubernetes environments.

    9.5k GitHub stars~3.9k tokensUpdated 3 days ago
    Auto-check passed
  • Higress Wasm Go Plugin

    higress-group/higress

    Develop Higress WASM plugins using Go 1.24+. An agent skill from higress-group/higress.

    9.5k GitHub stars~1.8k tokensUpdated 3 days ago
    Auto-check passed
  • Higress Auto Router

    higress-group/higress

    Configure automatic model routing using the get-ai-gateway.sh CLI tool for Higress AI Gateway.

    9.5k GitHub stars~954 tokensUpdated 3 days ago
    Auto-check passed
  • Higress Daily Report

    higress-group/higress

    生成 Higress 项目每日报告,追踪 issue/PR 动态,沉淀问题处理经验,驱动社区问题闭环。用于生成日报、跟进 issue、记录解决方案。

    9.5k GitHub stars~1.1k tokensUpdated 3 days ago
    Auto-check passed
  • Higress Update Envoy Gateway

    higress-group/higress

    Update Higress Envoy binary and gateway image dependencies for e2e validation.

    9.5k GitHub stars~1.2k tokensUpdated 3 days ago
    Auto-check passed

Questions about Agent Session Monitor

What does Agent Session Monitor do?

Real-time agent conversation monitoring - monitors Higress access logs, aggregates conversations by session, tracks token usage. Agent Session Monitor is an agent skill from higress-group/higress. Real-time agent conversation monitoring - monitors Higress access logs, aggregates conversations by session, tracks token usage.

When should I use Agent Session Monitor?

Agent Session Monitor fits situations like: users ask about current session token consumption; conversation history; cost statistics.

How do I install Agent Session Monitor in Claude Code?

Run `npx skills add higress-group/higress --skill agent-session-monitor -a claude-code`. Or copy the skill folder (.agents/skills/agent-session-monitor in higress-group/higress) into .claude/skills/agent-session-monitor in your project. Claude Code loads it when a task matches its description.

How do I install Agent Session Monitor in Codex?

Run `npx skills add higress-group/higress --skill agent-session-monitor -a codex`. Or copy the skill folder (.agents/skills/agent-session-monitor in higress-group/higress) into .agents/skills/agent-session-monitor in your project. Codex loads it when a task matches its description.

Can I use Agent Session Monitor in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add higress-group/higress --skill agent-session-monitor -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/agent-session-monitor, .gemini/skills/agent-session-monitor, .github/skills/agent-session-monitor and .opencode/skills/agent-session-monitor in your project.

What does Agent Session Monitor need to run?

Going by SKILL.md and its folder, Agent Session Monitor needs Python and a shell for the scripts in its folder and the command-line tools its instructions call (python3). Our summary lists: Python 3; A Bash shell.

Does Agent Session Monitor access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Agent Session Monitor safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Agent Session Monitor use?

Agent Session Monitor is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Agent Session Monitor use?

About 3.3k tokens (SKILL.md is roughly 13k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Agent Session Monitor?

Skills that share tags, products or a category with Agent Session Monitor: Statistics (thedaviddias/ux-patterns-for-developers, 259 stars), Sandbox Bench (vercel/next.js, 143k stars), Statistical Analysis (spacering-net/codeg, 3.9k stars) and Statsmodels (zLanqing/codex-claude-academic-skills, 4.7k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Agent Session Monitor?

higress-group (a GitHub organization) maintains it in higress-group/higress, which has 9,516 GitHub stars. The repository holds 11 skills in this directory. The repository was last updated on October 8, 2026.

Source: higress-group/higress on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.