What Is the /insights Command?
Hidden in plain sight within Claude Code is one of its most underrated features: the /insights command. This tool analyzes your local session history and generates an interactive HTML report that reveals your coding habits, recurring patterns, friction points, and workflow inefficiencies.
Announced in February 2026 by Anthropic engineer Thariq Shihipar, /insights is built with privacy in mind — it never sends data to external servers and works entirely with session files already stored on your machine. For indie developers and anyone working on sensitive codebases, that distinction matters.
Getting Started: Running /insights
Verify Your Claude Code Version
The /insights command requires a reasonably recent version of Claude Code. Before running it, check your version and update if needed.
# Check your current version
claude --version
# Update to the latest version
npm update -g @anthropic-ai/claude-codeRunning the Command
Inside any Claude Code session, simply type:
> /insights
Claude Code will then read your local session transcripts from the past 30 days and begin analysis. Depending on how many sessions you have, this may take anywhere from a few seconds to about a minute.
When analysis completes, an interactive HTML file is generated and you'll be prompted to open it in your browser. By default, reports are saved to ~/.claude/insights/.
# View generated reports
ls ~/.claude/insights/
# Example output: insights-2026-04-04.htmlUnderstanding Your Report: 6 Key Metrics
The generated report is organized into several sections, each giving you a different lens on how you work with Claude Code.
1. Session Overview
The top of the report gives you a quick summary of the analysis period:
- Total sessions: How many times you launched Claude Code in the last 30 days
- Average session length: How long a typical session runs
- Total conversation turns: The cumulative back-and-forth exchange count
- Peak usage hours: When during the day you're most active
This snapshot helps you understand your natural rhythm and whether your Claude Code usage aligns with your most productive hours.
2. Most-Used Commands and Features
This section ranks which slash commands (/clear, /resume, /project, etc.), file references (@filename), and subagent calls you reach for most often.
It's surprisingly revealing. You may discover you're constantly repeating manual steps that could be automated with a custom slash command, or that you're rarely using powerful features like worktrees or sub-agents that could dramatically speed up your work.
3. Recurring Patterns
Claude Code scans your sessions for repeated behaviors — things like:
- Issuing the same type of code modification request across sessions
- Pasting the same error messages over and over
- Referencing the same files repeatedly without having them in context upfront
These patterns are prime candidates for automation. Adding a few lines to CLAUDE.md or creating a custom slash command can often eliminate repetitive prompting entirely.
4. Friction Points
Friction points are moments where your workflow slows down — Claude misunderstands your intent, you make multiple correction requests in succession, or a task requires far more turns than it should.
Identifying these patterns helps you ask better initial questions, provide more complete context upfront, or add domain-specific rules to CLAUDE.md so Claude has the information it needs from the start.
5. Context Window Usage Trends
The report shows how much of Claude's context window you're typically using and how it trends across sessions. If you frequently hit high context usage:
- Consider using
/compactto compress conversation history - Break long tasks into smaller, focused sessions
- Structure your
CLAUDE.mdto front-load the most critical project context
6. Prompting Style Analysis
This section analyzes how you phrase your requests — the language patterns, instruction formats, and specificity levels you naturally gravitate toward.
Developers who consistently get better results from Claude tend to share common prompting habits: they specify expected output formats, provide relevant code snippets in context, and break complex requests into smaller steps. If your patterns diverge from these, the report often hints at where to improve.
Turning Insights Into Action
Reading a report is only half the work. Here's how to translate findings into real workflow improvements.
Update Your CLAUDE.md
The single highest-leverage change you can make is adding recurring patterns and implicit rules to CLAUDE.md. Once documented, Claude follows them automatically in every session without you needing to repeat yourself.
## Code Style Conventions
- Always use `interface` for TypeScript type definitions (not `type` aliases)
- Place test files in the `__tests__` directory adjacent to the source file
- Commit messages must follow Conventional Commits (feat:, fix:, docs:, etc.)
## Default Assumptions
- When adding a new API endpoint, always update the OpenAPI schema simultaneously
- When creating a new React component, generate a Storybook story file alongside itCreate Custom Slash Commands for Repeated Workflows
If insights reveal that you're frequently running the same multi-step workflow, package it as a custom slash command.
<!-- .claude/commands/new-endpoint.md -->
---
name: new-endpoint
description: Scaffold a new API endpoint with tests and OpenAPI schema
---
Create a new REST API endpoint with the following steps:
1. Add the route handler in src/routes/
2. Create corresponding TypeScript types in src/types/
3. Write unit tests in __tests__/routes/
4. Update the OpenAPI schema in openapi.yaml
5. Add a usage example to the README API sectionFor advanced productivity techniques, including how to combine worktrees with parallel sub-agents, see our Claude Code Parallel Development Mastery Guide.
Pair with /resume for Longer Sessions
Once you know which sessions tend to run long, you can plan for them better. The Claude Code Session Management and /resume Guide covers how to gracefully pause and continue complex multi-hour tasks without losing context.
Troubleshooting Common Issues
Report not generating at all
Insufficient session history: If you've just started using Claude Code, there may not be enough data to analyze. Build up at least several sessions first.
Outdated version: Run npm update -g @anthropic-ai/claude-code to ensure you're on a version that supports /insights.
File permission issues:
# Check permissions on the Claude config directory
ls -la ~/.claude/
# Repair if needed
chmod -R 755 ~/.claude/Report shows stale data
The analysis window is fixed at 30 days from the current date. Data from more than 30 days ago is not included. Run /insights regularly to keep up with evolving habits.
Some sessions seem missing from the analysis
Sessions with transcripts exceeding 30,000 characters are chunked into 25,000-character segments and summarized before analysis. Very long sessions will appear in the report at a summary level rather than with full detail.
/insights vs. /powerup: Which Should You Use?
Claude Code now includes two learning-oriented commands, and they serve complementary purposes.
/powerup is a structured tutorial system with 18 interactive, animated lessons that teach you what Claude Code can do. Use it when you want to discover features you haven't tried yet or build foundational knowledge. It's best for new users or anyone looking to expand their toolkit.
/insights is retrospective analysis for people already using Claude Code. It shows you not what's possible, but how you actually work — and where the gaps are. Use it after you've accumulated a few weeks of session data.
The ideal workflow:
- Run
/powerupto learn Claude Code features systematically - Put those features into practice for a few weeks
- Run
/insightsto see what's working, what's not, and what you've been overlooking - Implement changes in
CLAUDE.mdand custom commands - Repeat the cycle in a few weeks to measure improvement
Looking back
The /insights command is Claude Code's built-in coach for continuous self-improvement. Rather than guessing where you're losing time, it shows you exactly what your sessions reveal: the habits that are serving you well, the patterns that could be automated away, and the friction points worth fixing.
The key actions worth taking after reviewing your report:
- Encode your most common conventions and assumptions into
CLAUDE.md - Build custom slash commands for frequently repeated multi-step workflows
- Identify your high-friction sessions and adjust how you structure those prompts
- Revisit your context management strategy if usage trends are consistently high
Run /insights today, especially if you've been using Claude Code for a month or more. The findings often surprise even experienced users — and the improvements you make based on them compound over time.
For developers looking to push further, the Claude Code Parallel Development Mastery Guide shows how to structure worktrees and sub-agents into a workflow that can handle multiple features simultaneously.