session-profiler

Session Profiler

Turn one Hermes main transcript plus its subagent transcripts into analysis artifacts. Route every operation through the bundled wrapper so it uses a consistent environment and remembers the latest parsed work directory.

SP="$SKILL/scripts/sp"

Resolve SKILL to this skill's directory. If it is unavailable, use the absolute path to scripts/sp beside this file.

Workflow

1. Find and inspect the session.

$SP projects
$SP list [--provider hermes] [--n 20]
$SP list --project-dir "${HERMES_HOME:-$HOME/.hermes}/sessions"
$SP find <session-id-prefix>
$SP info <session-id-or-path>

Hermes stores rollouts under ${HERMES_HOME:-~/.hermes}/sessions/YYYY/MM/DD/rollout-*.jsonl and archived rollouts under archived_sessions/. Hermes subagent rollouts identify their parent thread recursively in session_meta.

1. Parse the session before analyzing it. Re-run this for a session that is still active.

$SP parse <session-id-or-main-jsonl-path>

The command prints and remembers its work directory. It writes events.parquet, events.csv, and agents.json. Override the remembered directory with global --data-dir <dir> or SESSION_DATA_DIR.

1. Start with a readable profile, then narrow the investigation.

$SP brief
$SP agent-summary
$SP costs
$SP slowest-tools --n 20 [--agent <id-or-name>]
$SP tool-breakdown [--agent <id-or-name>]
$SP inference-vs-tool
$SP errors
$SP turns
$SP timeline 2026-07-08T19:14:00Z --window 120
$SP events [--agent main] [--tool Bash] [--grep rebase] [--since 2026-07-08] [--n 30] [--long]

Use brief first when explaining a session to a person. It writes brief.md with the session's headline metrics, standout slow paths or failures, prompt trail or TOC storyline, and an agent scoreboard. Use the table commands for specific questions after the brief identifies the interesting region.

For ad hoc pandas analysis, set SESSION_DATA_DIR, add scripts/ to PYTHONPATH, and use from session_profiler.dataset import load; df = load() inside the wrapper's venv.