Skip to content
Back to search

mentor

mentor — a session-insights skill for AI coding agents. This skill reads your local Claude Code and OpenAI Codex history and writes an /insights-style HTML report on how you work: what you build, where you lose time, and concrete fixes. An agent skill for Claude Code, Codex, and any skills-capable agent.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/smixs--mentor/badge.svg)](/listings/smixs--mentor)

HTML

<a href="/listings/smixs--mentor"><img src="/api/listings/smixs--mentor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Recommended, via [skills.sh](https://skills.sh), the open marketplace for agent skills. One command installs the skill into any supported agent:

npx skills add smixs/mentor

Useful flags:

# globally, for every project
npx skills add smixs/mentor -g

# into specific agents
npx skills add smixs/mentor -a claude-code -a codex

# no questions, for CI
npx skills add smixs/mentor -g -y

Update the skill to the latest version: `npx skills update mentor`.

**Manual (Claude Code)** clones the skill straight into your skills directory:

git clone https://github.com/smixs/mentor.git ~/.claude/skills/mentor

For Codex, clone the skill into `~/.codex/skills/mentor` instead. The bundled scripts need [`uv`](https://github.com/astral-sh/uv); the skill itself is plain Markdown that any skills-capable agent can read.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 93 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![mentor skill](assets/banner.webp)
  2. # mentor
  3. ## a skill that reads your local session history and writes report on how you actually work.
  4. Agents now do the work juniors used to. But juniors became seniors by getting feedback from seniors. Give agents to juniors and retire the seniors, and that feedback loop disappears. This skill is that loop, packaged as an agent skill you install once and run every week.
  5. ![Example report](assets/report.webp)
  6. ## What the skill does
  7. - **Reads your local session history.** Claude Code transcripts under `~/.claude` and Codex rollouts under `~/.codex`. Nothing is uploaded; the skill runs entirely on your machine.
  8. - **Aggregates many sessions** into headline numbers (messages, sessions, tool calls, edits, files touched, tokens) plus per-day activity, tool mix, and languages.
  9. - **Writes one self-contained `report.html`** with eight sections, inline SVG icons, count-up numbers, and an animated chart. No dependencies and no build step, so any browser opens it.
  10. | Section | What it gives you |
  11. |---|---|
  12. | What you work on | Your sessions clustered into themes, with rough share |
  13. | How you use the agent | Tool ratios, languages, model tiering, checkpoints |
  14. | What you did well | Real wins, handed back |
  15. | Where things go wrong | Friction points, each with evidence and a concrete fix |
  16. | Features worth trying | Capabilities you under-use |
  17. | Suggested CLAUDE.md additions | Copy-paste lines that kill a recurring friction |
  18. | New ways to use it | Better workflows for your patterns |
  19. | On the horizon | Where your workflow is heading |
  20. The friction section is the point of the skill: every friction names a repeatable fix, a CLAUDE.md line, a hook, or a habit, so the same mistake stops showing up next week.
  21. ## Install the skill
  22. Recommended, via [skills.sh](https://skills.sh), the open marketplace for agent skills. One command installs the skill into any supported agent:
  23. ```bash
  24. npx skills add smixs/mentor
  25. ```
  26. Useful flags:
  27. ```bash
  28. # globally, for every project
  29. npx skills add smixs/mentor -g
  30. # into specific agents
  31. npx skills add smixs/mentor -a claude-code -a codex
  32. # no questions, for CI
  33. npx skills add smixs/mentor -g -y
  34. ```
  35. Update the skill to the latest version: `npx skills update mentor`.
  36. **Manual (Claude Code)** clones the skill straight into your skills directory:
  37. ```bash
  38. git clone https://github.com/smixs/mentor.git ~/.claude/skills/mentor
  39. ```
  40. For Codex, clone the skill into `~/.codex/skills/mentor` instead. The bundled scripts need [`uv`](https://github.com/astral-sh/uv); the skill itself is plain Markdown that any skills-capable agent can read.
  41. ## Use the skill
  42. Run the command, or just ask the agent for it in your own words ("review how I work with the agent", "разбери мои сессии"):
  43. ```
  44. /mentor # both agents, last 30 days (default)
  45. /mentor claude # Claude Code sessions only
  46. /mentor codex # OpenAI Codex sessions only
  47. /mentor both # cross-agent read: habits that show up in both tools
  48. ```
  49. Add a window with `--days N`. The skill writes the report to `~/.claude/usage-data/mentor-report.html` and opens it. Make the skill a weekly habit, since the patterns show up over runs, not in a single one:
  50. ```bash
  51. claude -p "/mentor both"
  52. ```
  53. ## How the skill works
  54. Three small scripts, no magic:
  55. 1. **`collect.py`** parses every session in the window into one stats bundle. The numbers are counted, not guessed.
  56. 2. The agent reads that digest and writes the eight-section analysis, grounded in your actual prompts and metrics.
  57. 3. **`render_report.py`** merges stats and analysis into the final HTML.
  58. The report is written in your language (English by default; Russian chrome is built into the skill). Some judgments, like themes and satisfaction, are model-inferred and flagged as such; read them as hypotheses, not verdicts.
  59. ## Privacy
  60. The skill reads local log files and writes a local HTML file. Your transcripts never leave your machine.
  61. ## License
  62. MIT, see [LICENSE](LICENSE). Русская версия: [README.ru.md](README.ru.md).
mentor/scripts/digest.py · Bundled script · 325 lines
  1. #!/usr/bin/env python3
  2. """Condense an agent session transcript into a compact digest the mentor reads.
  3. Works for two agents:
  4. - claude : Claude Code transcripts ~/.claude/projects/<slug>/<uuid>.jsonl
  5. - codex : OpenAI Codex rollouts ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
  6. (also ~/.codex/archived_sessions/rollout-*.jsonl)
  7. Both are JSONL but with different shapes; each parser normalizes to the same
  8. dict, so render() is shared. The digest keeps signal (verbatim user prompts,
  9. tool mix, token spend, correction signals) and drops noise (assistant prose,
  10. tool-result bodies).
  11. Usage:
  12. uv run --no-project python digest.py <path.jsonl>
  13. uv run --no-project python digest.py last --agent claude
  14. uv run --no-project python digest.py last --agent codex
  15. uv run --no-project python digest.py last --agent claude --exclude <session-id>
  16. uv run --no-project python digest.py --self-check
  17. """
  18. import json, sys, glob, os, re
  19. from collections import Counter
  20. from datetime import datetime
  21. CLAUDE_PROJECTS = os.path.expanduser("~/.claude/projects")
  22. CODEX_HOME = os.path.expanduser("~/.codex")
  23. # ponytail: heuristic only — the model does the real reading. Flags turns that
  24. # look like the user correcting/redirecting, a proxy for an under-specified goal.
  25. CORRECTION_RE = re.compile(
  26. r"\b(нет|не так|не то|стоп|подожди|я( же)? (просил|говорил|сказал)|зачем|"
  27. r"почему ты|верни|откати|отмени|это не|опять|снова|no,? |wrong|revert|undo|"
  28. r"that's not|not what|why did you|stop|i said|i asked)\b",
  29. re.IGNORECASE,
  30. )
  31. NOISE_MARKERS = ("<command-name>", "<local-command", "caveat", "<system-reminder",
  32. "tool_result", "[request interrupted", "<command-message>",
  33. "<recommended_plugins", "<user_instructions", "<environment_context")
  34. # Injected context blocks that agents prepend to the user's real message. The
  35. # real prompt lives AFTER them, so strip the blocks before deciding noise/real.
  36. # Codex wraps ambient UI state; Claude injects system reminders and hooks.
  37. INJECTED_TAGS = ("in-app-browser-context", "recommended_plugins", "environment_context",
  38. "user_instructions", "system-reminder", "user-prompt-submit-hook",
  39. "ide_context", "ide_opened_file", "local-command-caveat")
  40. def clean_injected(text):
  41. if not text:
  42. return ""
  43. for tag in INJECTED_TAGS:
  44. text = re.sub(rf"<{tag}\b.*?(</{tag}>|\Z)", "", text, flags=re.S | re.I)
  45. # Codex prefixes the real ask with this marker
  46. text = re.sub(r"^\s*#+\s*My request for Codex:\s*", "", text)
  47. return text.strip()
  48. def detect_agent(path):
  49. base = os.path.basename(path)
  50. return "codex" if base.startswith("rollout-") or "/.codex/" in path else "claude"
  51. def latest_transcript(agent, exclude=None):
  52. if agent == "codex":
  53. files = glob.glob(f"{CODEX_HOME}/sessions/**/rollout-*.jsonl", recursive=True)
  54. files += glob.glob(f"{CODEX_HOME}/archived_sessions/rollout-*.jsonl")
  55. else:
  56. files = [f for f in glob.glob(f"{CLAUDE_PROJECTS}/**/*.jsonl", recursive=True)
  57. if "/subagents/" not in f and "/tool-results/" not in f]
  58. if exclude:
  59. files = [f for f in files if exclude not in f]
  60. return max(files, key=os.path.getmtime) if files else None
  61. def is_real_prompt(text):
  62. if not text or not text.strip():
  63. return False
  64. head = text.lstrip()[:40].lower()
  65. if head.startswith("[") or head.startswith("<"):
  66. return False
  67. return not any(m in text.lower() for m in NOISE_MARKERS)
  68. EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
  69. def _blank(path, agent):
  70. return dict(path=path, agent=agent, meta={}, models=set(), skills=set(),
  71. prompts=[], tools=Counter(), out_tok=0, in_tok=0, cache_tok=0,
  72. corrections=0, interrupts=0, refusals=0, tool_errors=0,
  73. first_ts=None, last_ts=None, files=set(), edits=0)
  74. def parse_claude(path):
  75. d = _blank(path, "claude")
  76. for line in open(path, encoding="utf-8"):
  77. try:
  78. o = json.loads(line)
  79. except json.JSONDecodeError:
  80. continue
  81. ts = o.get("timestamp")
  82. if ts:
  83. d["first_ts"] = d["first_ts"] or ts
  84. d["last_ts"] = ts
  85. if o.get("cwd") and "cwd" not in d["meta"]:
  86. d["meta"]["cwd"] = o["cwd"]
  87. if o.get("gitBranch"):
  88. d["meta"]["branch"] = o["gitBranch"]
  89. if o.get("attributionSkill"):
  90. d["skills"].add(o["attributionSkill"])
  91. if o.get("interruptedMessageId"):
  92. d["interrupts"] += 1
  93. if o.get("apiRefusalCategory"):
  94. d["refusals"] += 1
  95. m = o.get("message")
  96. if not isinstance(m, dict):
  97. continue
  98. if m.get("model"):
  99. d["models"].add(m["model"])
  100. u = m.get("usage")
  101. if isinstance(u, dict):
  102. d["out_tok"] += u.get("output_tokens", 0) or 0
  103. d["in_tok"] += u.get("input_tokens", 0) or 0
  104. d["cache_tok"] += (u.get("cache_read_input_tokens", 0) or 0) + \
  105. (u.get("cache_creation_input_tokens", 0) or 0)
  106. role = m.get("role")
  107. if role == "user" and not o.get("isMeta"):
  108. c = m.get("content")
  109. raw = c if isinstance(c, str) else "\n".join(
  110. b["text"] for b in c if isinstance(b, dict) and b.get("type") == "text"
  111. ) if isinstance(c, list) else ""
  112. t = clean_injected(raw)
  113. if is_real_prompt(t):
  114. d["prompts"].append(t)
  115. if CORRECTION_RE.search(t):
  116. d["corrections"] += 1
  117. if isinstance(c, list):
  118. for b in c:
  119. if isinstance(b, dict) and b.get("type") == "tool_result" and b.get("is_error"):
  120. d["tool_errors"] += 1
  121. elif role == "assistant":
  122. c = m.get("content")
  123. if isinstance(c, list):
  124. for b in c:
  125. if isinstance(b, dict) and b.get("type") == "tool_use":
  126. name = b.get("name", "?")
  127. d["tools"].update([name])
  128. if name in EDIT_TOOLS:
  129. d["edits"] += 1
  130. fp = (b.get("input") or {}).get("file_path")
  131. if fp:
  132. d["files"].add(fp)
  133. return d
  134. def parse_codex(path):
  135. d = _blank(path, "codex")
  136. last_usage = None
  137. for line in open(path, encoding="utf-8"):
  138. try:
  139. o = json.loads(line)
  140. except json.JSONDecodeError:
  141. continue
  142. ts = o.get("timestamp")
  143. if ts:
  144. d["first_ts"] = d["first_ts"] or ts
  145. d["last_ts"] = ts
  146. p = o.get("payload") if isinstance(o.get("payload"), dict) else {}
  147. pt = p.get("type")
  148. if o.get("type") == "session_meta":
  149. if p.get("cwd"):
  150. d["meta"].setdefault("cwd", p["cwd"])
  151. elif o.get("type") == "turn_context":
  152. if p.get("cwd") and "cwd" not in d["meta"]:
  153. d["meta"]["cwd"] = p["cwd"]
  154. if p.get("model"):
  155. d["models"].add(p["model"])
  156. elif pt == "user_message":
  157. t = clean_injected(p.get("message", ""))
  158. if is_real_prompt(t):
  159. d["prompts"].append(t)
  160. if CORRECTION_RE.search(t):
  161. d["corrections"] += 1
  162. elif pt == "custom_tool_call":
  163. d["tools"].update([p.get("name", "?")])
  164. elif pt == "function_call":
  165. d["tools"].update([p.get("name", "function_call")])
  166. elif pt == "mcp_tool_call_end":
  167. d["tools"].update(["mcp_tool"])
  168. elif pt == "web_search_end":
  169. d["tools"].update(["web_search"])
  170. elif pt == "patch_apply_end":
  171. d["edits"] += 1
  172. fp = p.get("path") or (p.get("changes") or {})
  173. if isinstance(fp, str):
  174. d["files"].add(fp)
  175. elif isinstance(fp, dict):
  176. d["files"].update(fp.keys())
  177. elif pt == "custom_tool_call_output":
  178. out = p.get("output")
  179. if isinstance(out, dict) and (out.get("exit_code") not in (0, None)):
  180. d["tool_errors"] += 1
  181. elif pt == "token_count":
  182. info = p.get("info") or {}
  183. tot = info.get("total_token_usage") or {}
  184. if tot:
  185. last_usage = tot # cumulative — keep the latest
  186. if last_usage:
  187. d["out_tok"] = (last_usage.get("output_tokens", 0) or 0) + \
  188. (last_usage.get("reasoning_output_tokens", 0) or 0)
  189. d["in_tok"] = last_usage.get("input_tokens", 0) or 0
  190. d["cache_tok"] = last_usage.get("cached_input_tokens", 0) or 0
  191. return d
  192. def parse(path, agent=None):
  193. agent = agent or detect_agent(path)
  194. return parse_codex(path) if agent == "codex" else parse_claude(path)
  195. def duration(a, b):
  196. try:
  197. d = datetime.fromisoformat(b[:19]) - datetime.fromisoformat(a[:19])
  198. mins = int(d.total_seconds() // 60)
  199. return f"{mins//60}h {mins%60}m" if mins >= 60 else f"{mins}m"
  200. except Exception:
  201. return "?"
  202. def render(d):
  203. tot_tools = sum(d["tools"].values())
  204. top = ", ".join(f"{n}×{c}" for n, c in d["tools"].most_common(12))
  205. L = [f"# Session digest [{d['agent']}] — {os.path.basename(d['path'])}\n"]
  206. L.append(f"- cwd: `{d['meta'].get('cwd')}` branch: `{d['meta'].get('branch','n/a')}`")
  207. L.append(f"- model(s): {', '.join(sorted(d['models'])) or '?'}")
  208. L.append(f"- span: {d['first_ts']} → {d['last_ts']} ({duration(d['first_ts'], d['last_ts'])})")
  209. if d["agent"] == "claude":
  210. L.append(f"- skills invoked: {', '.join(sorted(d['skills'])) or 'none'}")
  211. L.append("\n## Metrics")
  212. L.append(f"- user prompts: **{len(d['prompts'])}**")
  213. L.append(f"- tool calls: **{tot_tools}** ({top})")
  214. L.append(f"- output tokens: **{d['out_tok']:,}** | input(+cache): {d['in_tok']+d['cache_tok']:,}")
  215. L.append(f"- correction-like prompts (heuristic): **{d['corrections']}** | "
  216. f"interrupts: {d['interrupts']} | tool errors: {d['tool_errors']} | refusals: {d['refusals']}")
  217. L.append("\n## User prompts (verbatim — analyze HOW goals were framed)")
  218. for i, p in enumerate(d["prompts"], 1):
  219. L.append(f"{i}. {p[:500].replace(chr(10), ' ')}")
  220. return "\n".join(L)
  221. def _self_check():
  222. import tempfile
  223. claude_rows = [
  224. {"type": "user", "timestamp": "2026-07-19T01:00:00Z", "cwd": "/tmp", "gitBranch": "main",
  225. "message": {"role": "user", "content": "сделай X с чётким критерием"}},
  226. {"type": "assistant", "message": {"role": "assistant", "model": "claude-fable-5",
  227. "usage": {"output_tokens": 100, "input_tokens": 5, "cache_read_input_tokens": 10},
  228. "content": [{"type": "tool_use", "name": "Bash"}]}},
  229. {"type": "user", "message": {"role": "user", "content": "нет, я же просил не так"}},
  230. # real prompt hidden behind an injected reminder block — must still be extracted
  231. {"type": "user", "message": {"role": "user",
  232. "content": "<system-reminder>bg noise</system-reminder>\nисправь баг в файле"}},
  233. {"type": "user", "isMeta": True, "message": {"role": "user", "content": "<system-reminder>x</system-reminder>"}},
  234. ]
  235. codex_rows = [
  236. {"type": "session_meta", "timestamp": "2026-07-19T01:00:00Z",
  237. "payload": {"type": "session_meta", "cwd": "/tmp/proj"}},
  238. {"type": "turn_context", "payload": {"type": "turn_context", "model": "gpt-5.6-sol", "cwd": "/tmp/proj"}},
  239. {"type": "event_msg", "payload": {"type": "user_message", "message": "собери данные и покажи"}},
  240. {"type": "response_item", "payload": {"type": "custom_tool_call", "name": "exec", "input": "ls"}},
  241. {"type": "event_msg", "payload": {"type": "user_message", "message": "no, wrong, revert that"}},
  242. # the real ask sits AFTER an ambient block and the Codex marker
  243. {"type": "event_msg", "payload": {"type": "user_message", "message":
  244. "\n<in-app-browser-context source=\"ambient-ui-state\">\nstate\n</in-app-browser-context>\n\n## My request for Codex:\nсделай спиннеры поменьше"}},
  245. {"type": "response_item", "payload": {"type": "patch_apply_end", "path": "/tmp/proj/app.ts"}},
  246. {"type": "response_item", "payload": {"type": "function_call", "name": "apply_patch"}},
  247. {"type": "event_msg", "timestamp": "2026-07-19T01:05:00Z", "payload": {"type": "token_count",
  248. "info": {"total_token_usage": {"input_tokens": 200, "output_tokens": 50,
  249. "reasoning_output_tokens": 20, "cached_input_tokens": 30}}}},
  250. ]
  251. for rows, agent in [(claude_rows, "claude"), (codex_rows, "codex")]:
  252. with tempfile.NamedTemporaryFile("w", suffix=".jsonl", delete=False) as fh:
  253. for r in rows:
  254. fh.write(json.dumps(r) + "\n")
  255. path = fh.name
  256. d = parse(path, agent)
  257. os.unlink(path)
  258. if agent == "claude":
  259. assert len(d["prompts"]) == 3, d["prompts"] # incl. the reminder-wrapped one
  260. assert "исправь баг в файле" in d["prompts"], d["prompts"]
  261. assert d["corrections"] == 1 and d["out_tok"] == 100
  262. assert d["tools"]["Bash"] == 1 and "claude-fable-5" in d["models"]
  263. else:
  264. assert len(d["prompts"]) == 3, d["prompts"] # ambient-wrapped prompt recovered
  265. assert "сделай спиннеры поменьше" in d["prompts"], d["prompts"]
  266. assert d["corrections"] == 1, d["corrections"] # "no, wrong, revert"
  267. assert d["out_tok"] == 70, d["out_tok"] # 50 + 20 reasoning
  268. assert d["in_tok"] == 200 and d["cache_tok"] == 30
  269. assert d["tools"]["exec"] == 1 and d["tools"]["apply_patch"] == 1
  270. assert d["edits"] == 1 and "/tmp/proj/app.ts" in d["files"]
  271. assert "gpt-5.6-sol" in d["models"]
  272. assert "Session digest" in render(d)
  273. print("self-check OK (claude + codex)")
  274. def main(argv):
  275. if "--self-check" in argv:
  276. return _self_check()
  277. agent = argv[argv.index("--agent") + 1] if "--agent" in argv else None
  278. exclude = argv[argv.index("--exclude") + 1] if "--exclude" in argv else None
  279. skip = {exclude, agent}
  280. target = next((a for a in argv[1:] if not a.startswith("--") and a not in skip), None)
  281. if target in (None, "last"):
  282. path = latest_transcript(agent or "claude", exclude)
  283. if not path:
  284. sys.exit(f"no {agent or 'claude'} transcript found")
  285. else:
  286. path = os.path.expanduser(target)
  287. if not os.path.exists(path):
  288. sys.exit(f"not found: {path}")
  289. print(render(parse(path, agent)))
  290. if __name__ == "__main__":
  291. main(sys.argv)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.