Claude Code /insights: audit how you work with it

You repeat the same instructions every session, reach for tools that waste context, and let the AI make decisions you should be making yourself. After a few weeks with an AI coding assistant you also develop good habits: you learn which prompts get better results, which tasks to delegate, when to step in.

The problem is you can’t see any of this while you’re in the flow. You’d need someone watching over your shoulder across dozens of sessions, spotting the patterns you can’t. Which of your habits are costing you time, and what do you change first?

Claude Code has a built-in command that does that job. It reads your recent sessions and writes a report on how you work with it, where sessions go wrong, and what to change. Other assistants have no command of the same name, so this guide is for people who use Claude Code most days.

Part 1 of 4 Learn

Run the command

Open Claude Code in any project folder and type:

/insights

The command reads the sessions saved on this computer and builds the report from them. A single run analyses up to 200 sessions it hasn’t analysed before and skips very short ones. If it leaves some out, the report header shows how many it analysed with the total in brackets, for example 200 sessions (412 total). Claude Code deletes session files older than 30 days by default, so in practice the report covers about the last month.

The report only covers sessions saved on this computer. Sessions from your other machines, Claude Code on the web, and chats on claude.ai aren’t included, and the command isn’t available in cloud sessions.

Once it finishes, you’ll find the report as a web page saved at ~/.claude/usage-data/report.html. Each run also saves a copy with the date and time in its name, so earlier reports aren’t overwritten. Open the file in your browser to read it.

If what you want to know is how much of your plan is left, run /usage instead. It shows your plan limits and session cost.

What the report tells you

The report opens with At a Glance: what’s working, what’s hindering you, quick wins to try, and ambitious workflows. Then come a few numbers (messages, lines and files changed, days active, messages per day) and charts, including what time of day you tend to work. The sections below use the report’s own headings, and everything in them comes from your own sessions.

What You Work On

The report groups your sessions into four or five project areas, with a session count and a short description of each. This is the overview: where you’re spending your time and what kind of work you’re asking Claude to do.

If you see an area with 15 sessions that are all short, that’s worth a look: either the work is quick, or you’re switching context often.

How You Use Claude Code

A few paragraphs, written to you, on how you interact with Claude Code: how much you plan before you ask, how often you step in, how you hand over work.

Impressive Things You Did

Three workflows where you and Claude Code work well together, with what you did in them. These might be a prompting style that gets working code on the first pass, or a habit of giving context up front that cuts the back-and-forth.

Use this section to decide what to keep doing. When a workflow works, find out why, so you can copy it into other projects.

Where Things Go Wrong

This is the section worth reading twice. Claude Code reads each session and counts friction of these kinds:

• a misunderstood request
• a wrong approach
• buggy code
• an action you rejected
• Claude getting blocked
• you stopping early
• the wrong file or location
• changes bigger than you asked for
• slow or wordy answers
• your own request being unclear
• problems outside Claude Code

The report then names your three biggest friction categories and gives two examples of each from your sessions. You’ll recognise the moments.

Existing CC Features to Try and New Ways to Use Claude Code

CC in this heading stands for Claude Code, and this is the section you copy from. The suggestions come in three kinds:

• CLAUDE.md additions: lines to add to your CLAUDE.md file, each with why it would help and where to put it. The analysis gives priority to instructions you’ve typed in two or more sessions, because you shouldn’t have to keep repeating them.
• Features to try: two or three Claude Code features picked for how you work, from MCP servers, skills, hooks, headless mode and subagents, each with a command or setting to copy.
• New ways to use it: short suggestions, each with a prompt you can copy and try.

After those comes On the Horizon, a few bigger ideas for what you could hand over to Claude Code later. Read those for interest. The suggestions above are where the changes for this week come from.

When auto mode is available to you and most of your recent sessions ran without it, the report can also estimate how many permission prompts auto mode could have handled for you.

How to read the results

Start with what’s working, before you go to the problems. Seeing your effective patterns written down helps you understand your own workflow, and makes it easier to teach those patterns to others on your team.

After the strengths, look at the friction. A friction point that happens once is an anecdote, and one that shows up across several sessions is a pattern worth fixing.

For each recurring friction point, ask: is this a prompting problem, a context problem, or a tooling problem?

• Prompting problems mean your instructions are ambiguous or incomplete. The fix is usually a CLAUDE.md rule that makes the implicit explicit.
• Context problems mean Claude doesn’t know something it needs to know. The fix is adding project context, such as architecture notes, coding conventions or key decisions, where Claude can find it.
• Tooling problems mean you’re doing by hand what could be automated. The fix is a skill, a hook, or an MCP server connection.

Made-up friction points for illustration, written the way an /insights report describes them. They are not from a real report.

Prompting, context or tooling?

How to read this

Sort each friction point into the kind of problem it is. The fix that matches appears underneath.

Prompting

0

Your instructions were ambiguous or incomplete.

Fix: A CLAUDE.md rule that makes the implicit explicit.

Context

0

Claude didn’t know something it needed to know.

Fix: Project context, such as architecture notes, coding conventions or key decisions, where Claude can find it.

Tooling

0

You did by hand what could be automated.

Fix: A skill, a hook or an MCP server connection.

1. Asked for a fix to one function; Claude also rewrote two others in the same file.

   PromptingContextTooling

   Prompting. The request didn’t say how far the change should go. Fix: Add a CLAUDE.md rule such as “Only change the code the request names; ask before editing anything else.” Prompting, says the guide. The request didn’t say how far the change should go. Fix: Add a CLAUDE.md rule such as “Only change the code the request names; ask before editing anything else.”

2. You typed the same five-step release checklist at the end of four sessions.

   PromptingContextTooling

   Tooling. It’s the same multi-step instruction every time. Fix: Write it once as a skill and run it with one slash command. Tooling, says the guide. It’s the same multi-step instruction every time. Fix: Write it once as a skill and run it with one slash command.

3. Claude wrote tests in Jest syntax; this project’s tests run on Vitest.

   PromptingContextTooling

   Context. Claude had no way to know which test tool the project uses. Fix: Write the project’s coding conventions, including the test tool, where Claude can find them. Context, says the guide. Claude had no way to know which test tool the project uses. Fix: Write the project’s coding conventions, including the test tool, where Claude can find them.

4. Code failed the formatter after Claude’s edits, in six sessions.

   PromptingContextTooling

   Tooling. The check should happen automatically. Fix: Set up a hook that runs your formatter after every file edit. Tooling, says the guide. The check should happen automatically. Fix: Set up a hook that runs your formatter after every file edit.

5. You asked Claude to “tidy up the report” and it changed the layout when you meant the wording.

   PromptingContextTooling

   Prompting. The request could be read two ways. Fix: Add a CLAUDE.md rule such as “When a request could mean layout or wording, ask which before editing.” Prompting, says the guide. The request could be read two ways. Fix: Add a CLAUDE.md rule such as “When a request could mean layout or wording, ask which before editing.”

6. Claude added the new page to the old folder; the team moved pages to a new one last month.

   PromptingContextTooling

   Context. A key decision about the project wasn’t written anywhere Claude reads. Fix: Add architecture notes that record where pages live now, and why. Context, says the guide. A key decision about the project wasn’t written anywhere Claude reads. Fix: Add architecture notes that record where pages live now, and why.

7. You pasted ticket details from your issue tracker into the chat by hand, in most sessions.

   PromptingContextTooling

   Tooling. Claude can’t reach the issue tracker, so you do the copying. Fix: Connect an MCP server for the issue tracker. Tooling, says the guide. Claude can’t reach the issue tracker, so you do the copying. Fix: Connect an MCP server for the issue tracker.

8. Claude explained each change at length when you only wanted the code.

   PromptingContextTooling

   Prompting. You never said how much explanation you wanted. Fix: Add a CLAUDE.md rule such as “Reply with the code and one line on what changed, unless I ask for more.” Prompting, says the guide. You never said how much explanation you wanted. Fix: Add a CLAUDE.md rule such as “Reply with the code and one line on what changed, unless I ask for more.”

9. Claude asked which of three settings files is the live one, in five sessions.

   PromptingContextTooling

   Context. Only you know which settings file is the live one, and nothing in the project says so. Fix: Add a note on how the project is put together, naming the live settings file. Context, says the guide. Only you know which settings file is the live one, and nothing in the project says so. Fix: Add a note on how the project is put together, naming the live settings file.

Nothing sorted yet.

One change for each

• Prompting: A CLAUDE.md rule that makes the implicit explicit.
• Context: Project context, such as architecture notes, coding conventions or key decisions, where Claude can find it.
• Tooling: A skill, a hook or an MCP server connection.

Start over

This page sends nothing anywhere. Your answers stay in your browser.

How to read this

The /insights report names your biggest friction categories, with examples from your sessions. Before you fix one, ask what kind of problem it is.

Prompting: your instructions were ambiguous or incomplete. Context: Claude didn’t know something it needed to know. Tooling: you did by hand what could be automated.

Drag each line onto a box, or use the buttons under it. The fix appears underneath, and the guide’s answer is outlined in red. Once you have chosen, the answer stays.

A hook runs a command at a set point, such as after every file edit. A skill is a file of instructions you run with one slash command. An MCP server lets Claude use another tool, such as your issue tracker.

The friction points are written by hand to show the idea. They are not from a real report.

Got it

---

Apply what you find

Pick the top three friction categories. The report names three; if one of them doesn’t cost you much, swap in a problem from its examples that does.

For each one, make exactly one change:

1. Add a CLAUDE.md rule for a prompting or context problem, when the fix is “Claude needs to know this about my project.” One line, specific, testable. “Always run tests before committing” is good. “Write better code” is useless.
2. Create a skill if you’re typing the same multi-step instruction again and again. A skill is a Markdown file of instructions that you run with one slash command, so you write the workflow once and reuse it. The report often suggests these directly.
3. Set up a hook if the fix is “this should be checked automatically.” A hook runs a command at a set point, such as after every file edit, so formatting or type checks happen before you notice a problem. To create one, ask Claude Code to write it for you: “Create a hook that runs my formatter after every file edit”.

If a tooling problem comes from Claude not being able to reach another tool, such as your issue tracker, the fix may be an MCP server connection instead. Claude Code MCP: add a server and check it works covers that.

Then work normally for a week and run /insights again. Compare its Where Things Go Wrong section with the last one, looking at two things: whether each category you worked on is still in the top three, and whether its new examples show the same problem.

New problems may appear in that second report. That’s normal, because fixing one problem lets the next one show.

The second report only analyses sessions since the first, so it covers about a week. Expect fewer examples and read the comparison as a rough guide.

Long sessions are shortened, and the suggestions can be wrong

Claude Code shortens each session before it analyses it. It keeps the first 500 characters of each of your messages and the first 300 of each of Claude’s, and any session over 30,000 characters of that text is split into chunks and summarised before the analysis. The insights are still useful, but detail from long sessions gets compressed.

A model reads those shortened sessions and writes the report, so a friction example or a suggested rule can be wrong. Check a suggested CLAUDE.md line against what happened before you add it.

Part 2 of 4 Practise

Try it on your own work

1. Run /insights in Claude Code on the computer you use most.Result the report is written to ~/.claude/usage-data/report.html, and its header shows how many sessions it analysed.

2. Save a copy of the report somewhere outside ~/.claude, with today’s date in the name.Result you have a report you can still open after Claude Code’s 30-day clean-up.

3. Read Impressive Things You Did first. Write down one habit to keep.Result one sentence describing something you already do that works.

4. Take the three friction categories from Where Things Go Wrong, and label each one prompting, context or tooling.Result three lines, each with a category and one label.

5. Make one change for each: a CLAUDE.md rule, a skill or a hook, whichever matches the label.Result three changes, each specific enough that you could tell next week whether it worked.

6. A week later, run /insights again and compare Where Things Go Wrong with your saved copy.Result for each of your three categories, you can say whether it’s still in the top three and whether the new examples show the same problem, so you know which change worked and which needs another try.

Part 3 of 4 Check

Check yourself

It's early December and you want to compare this month's report with the one you ran in early November, but the November file has gone from ~/.claude/usage-data. What happened, and what do you do from now on?

Claude Code deletes reports on the same schedule as your sessions, after 30 days by default. From now on, save a copy of report.html somewhere outside ~/.claude each time you run /insights, with the date in the name.

One of your friction categories is Claude changing more than you asked: you asked for a fix to one function and it rewrote two others. Is that a prompting, context or tooling problem, and what's the fix?

Prompting. Your request didn’t say how far the change should go. Add a rule to CLAUDE.md such as “Only change the code the request names; ask before editing anything else”, and say the scope in the request itself when it matters.

The report shows you type the same five-step release checklist to Claude at the end of most weeks. Which fix matches?

A skill. It’s the same multi-step instruction every time, so write it once as a skill and run it with one slash command.

Your top friction is code that fails the formatter after Claude edits a file. Which fix matches?

A hook. It’s a tooling problem: the check should happen automatically. Set up a hook that runs your formatter after each file edit, so the problem is caught before you see it.

A week after your three changes, one category is still in the top three and its new examples show the same problem. What do you do?

Check whether your change was specific enough, and whether it was the right kind of fix. A vague rule, or a CLAUDE.md line for something that needed a hook, often explains it. Change that one fix and compare again the following week.

Part 4 of 4 Keep

Keep this

Run it monthly and change three things at a time

• Run /insights once a month and save a copy of each report outside ~/.claude, so you can compare months.
• Read what’s working before the friction.
• Fix three friction categories at a time, one change each, then check again a week later.
• Check a suggested CLAUDE.md line against what happened before you add it.
• Remember the analysis uses your plan and sends your transcripts to Claude, the same as a normal session.

In the Kit Library, members can get a friction log to fill in after each /insights run, with the fix and a prompt for each category.

Print this card

Read next

• Setting Up Your First CLAUDE.md File: where most of the fixes from your report end up.
• What claude doctor and /doctor check: another built-in Claude Code check, this time on your setup.
• Claude Code MCP: add a server and check it works: the fix for a tooling problem where Claude can’t reach another tool.