/hermes-insights

name: hermes-insights
description: Generate insights about your Claude Code usage — what topics you work on most, common patterns, productivity trends.
version: 1.0.0
author: hermes-CCC (ported from Hermes Agent by NousResearch)
license: MIT
metadata:
  hermes:
    tags: [Analytics, Insights, Usage, Productivity]
    related_skills: [hermes-search, honcho]

hermes-insights

Analyze your Claude Code usage patterns across sessions and produce a structured insight report: what topics you work on most, which skills you use, what types of projects dominate your workflow, and where your productivity is strongest.

Invocation

/hermes-insights
/hermes-insights --days <N>

---

Subcommands

`/hermes-insights` — Full Analysis

Analyzes all available memory files and session history with no time constraint.

`/hermes-insights --days <N>` — Time-Bounded Analysis

Restricts analysis to session files created in the last N days.

**How Claude filters by date:**

find ~/.claude/projects/*/memory/session_*.md \
     -mtime -<N> -type f

---

Data Sources and What Claude Analyzes

1. Memory Files — Topic and Theme Extraction

ls ~/.claude/projects/*/memory/session_*.md

For each session file, Claude reads the `decisions`, `facts_learned`, `artifacts_created`, and `open_issues` sections and extracts noun phrases as topic signals. Topics are then counted and ranked by frequency across all sessions.

**Output:** Top 10 topics, each with session count and a representative example decision or fact.

2. Skills Used — Skill Utilization

ls ~/.claude/skills/
ls ~/.claude/projects/*/skills/ 2>/dev/null

Claude counts which skill directories exist and cross-references session memory files for any `/skill-name` invocation patterns mentioned in the `decisions` or `facts_learned` fields.

**Output:** Skill utilization table (skill name, invocation count estimate, last used date).

3. Project Types and Domains

Claude reads each session file's `project:` field (from the hermes-compress YAML) and groups sessions by project slug. It then infers the domain from artifact paths and topic keywords (e.g., `.py` artifacts + "Neo4j" keywords → "graph database / Python backend").

**Output:** Project breakdown table (project, session count, primary domain, last active date).

4. Conversation Patterns

Claude counts per-session: number of decisions made, artifacts created, problems solved, and open issues left unresolved. These become productivity metrics.

**Output:** Per-week averages for decisions, artifacts, and resolution rate (problems solved / open issues ratio).

5. Data Hygiene and Confidence Rules

• Skip any session file that is missing the expected `hermes-compress` YAML block and record how many files were excluded.
• Normalize topic strings by lowercasing, trimming punctuation, and folding obvious singular/plural variants before counting.
• Prefer explicit evidence from `decisions` and `artifacts_created` over weak inference from prose when assigning project domains.
• Mark a skill as `inferred` if the file only mentions the skill name indirectly and no `/skill-name` invocation is present.
• Downgrade trend claims to `low confidence` when fewer than 5 sessions match the selected date range.
• Report `no sessions matched the filter` instead of fabricating empty charts when `--days <N>` returns zero files.
• Treat duplicate session paths with identical timestamps as one observation so repeated syncs do not inflate counts.
• Fall back to `unknown project` when the `project:` field is absent and artifact paths do not provide a clear slug.
• Separate unresolved carry-over work from newly opened issues so the resolution rate is not overstated.

---

Full Output Structure

## Claude Code Usage Insights
Generated: 2026-04-07 | Sessions analyzed: 23 | Date range: 2026-02-14 – 2026-04-07

### Top Topics
| Rank | Topic              | Sessions | Example |
|------|--------------------|----------|---------|
| 1    | Neo4j / graph DB   | 14       | "Use Neo4j as primary ontology store" |
| 2    | FastAPI / Python   | 11       | "REST endpoints for /query and /ingest" |
| 3    | Vercel deployment  | 7        | "Deploy to Vercel with vercel link --repo" |
| 4    | OpenCrab ontology  | 6        | "Fallback to neo4j when opencrab returns 0" |
| 5    | Discord integration| 4        | "Reply via plugin_discord_discord reply tool" |

### Skill Utilization
| Skill             | Est. Invocations | Last Used  |
|-------------------|-----------------|------------|
| hermes-compress   | 18              | 2026-04-07 |
| hermes-memory     | 12              | 2026-04-05 |
| hermes-search     | 9               | 2026-04-06 |
| hermes-persona    | 5               | 2026-04-03 |
| honcho            | 3               | 2026-03-28 |

### Project Breakdown
| Project       | Sessions | Domain                  | Last Active |
|---------------|----------|-------------------------|-------------|
| ontology      | 14       | Graph DB / Python API   | 2026-04-07 |
| AlexAI        | 6        | LLM product / strategy  | 2026-04-02 |
| hermes-CCC    | 3        | Claude Code skills      | 2026-04-07 |

### Productivity Trends (weekly averages)
- Decisions per session: 4.2
- Artifacts created per session: 2.8
- Problems solved per session: 1.9
- Resolution rate: 68% (open issues closed within 2 sessions)

### Recommendations
- **Automate Neo4j setup:** It appears in 61% of sessions. Consider a project template.
- **Increase hermes-compress frequency:** 5 sessions have no memory file (no compress run).
- **hermes-persona unused in recent sessions:** Last used 4 days ago — may boost focus in coder mode.

### Key Takeaway
You are most productive in graph database and Python API work, averaging 2.8 artifacts per session, with a 68% issue resolution rate.

---

How Claude Gathers the Data

1. List all session memory files: `ls -t ~/.claude/projects/*/memory/sessi