AI Agents have become a daily driver for most developers, but very few people stop and reflect on how they are actually using them. Bad habits compound silently. Soon you're reaching for the same broken prompt every morning, re-explaining the same three project gotchas to every fresh session, and losing an hour debugging because the agent claimed to be "done" without testing anything.
/insights is Claude Code's built-in reflection tool. It reads the last 30 days of your conversation history and turns it into a personalized report on how you actually work with your agent, where you get stuck, and what to you can change.
/insights do?By running /insights in any Claude Code session, Claude analyses the last 30 days of conversations stored under ~/.claude/. The output from this is an interactive HTML report saved to ~/.claude/usage-data/report - a static file you can open in any browser.
Privacy - /insights only reads the session metadata under ~/.claude/. It never touches the files in your repositories.
The report walks from a high-level summary down to copy-paste suggestions, and typically, you'll find the most valuable sections are:
CLAUDE.md additions plus tailored recommendations for Skills, Hooks, or MCP serversLike many things, reflecting on your own behaviour without bias is hard, and looking through 30 days of your own conversations manually is to find patterns is even harder. /insights takes over this reflection process and does the pattern-matching for you.
Without /insights - You "feel" your AI workflow is slow but cannot point to the exact reason why. You keep retyping the same three-step prompt because it never occurred to you it could be a Skill. You assume the agent's "done" messages are correct because checking each one is annoying.
❌ Figure: Bad example - Using Claude Code with /insights nor reflecting on your own Agent usage
With /insights - The report names that three-step prompt as your most-repeated workflow and suggests turning it into a Skill. Your friction list flags premature "done" claims as the top recurring issue. You ship two CLAUDE.md additions in the next 10 minutes.
✅ Figure: Good example - Using Claude Code with /insights to identify the problematic patterns on your own behavior and actioning productive changes
Having the report and reading through it is great, but a report with feedback that you don't action is wasted. After every run, you should always try to do one of the following:
AGENTS.md so it flows to every tool that reads it. The "Suggested CLAUDE.md additions" section gives you a head startgit status or a smoke test after edits will catch them automaticallyCLAUDE.md or a Skill, not in mid-session promptsWarning: The suggestions are pattern-matched from repetition, not judgement. They can codify a bad habit as easily as a good one. Treat them as drafts. Read each one and ask yourself whether it would actually help future-you before actioning them.
/insights is a Claude Code exclusive command. There is no equivalent in Cursor, GitHub Copilot, Gemini CLI, or Codex CLI today. The underlying idea of "analyse my recent sessions and tell me how to use this tool better", however, is something you can replicate yourself with a custom Skill or prompt that walks your tool's session logs and surfaces the same patterns.
For more on skills, checkout our rule on Do you use Skills to standardize your AI workflows? Although the output will not be as polished as Claude's interactive HTML report, the reflection step is what matters, not the chart styling.
Although there is no limit on how often you run it, typically, monthly is the sweet spot. Since /insights analyzes the last 30 days of conversations, running it weekly is often too noisy and can't reveal real change in behaviour, as there are not enough sessions for real pattern changes to emerge. Whilst quarterly is too long apart, and bad habits have already solidified and done its damage.
Tip: You can pin /insights to the same day as your sprint retrospective every month, for example, right before the first Sprint Review of every month.