Have You Stared at Claude Code’s Cursor Blinking for Five Minutes Without Knowing What It’s Doing
Last week I had Claude Code help me refactor a React project with 47 components. After hitting enter, the cursor on the screen started blinking.
One minute passed, nothing.
Three minutes passed, still nothing.
I started wondering if it got stuck, if it misunderstood my instructions, or if it was stuffing something weird into my code. Later I added a progress reporting prompt to CLAUDE.md and solved this problem. But before that, it felt like ordering food delivery—the tracking page showed “Rider has accepted” and then never updated again. You didn’t know if they were already downstairs or had ridden to the wrong neighborhood.
This problem is especially common among Claude Code users. Someone on Reddit complained “I had it process 100 files, waited 8 minutes and saw nothing, finally ctrl+c’d and started over.” There are also issues filed on GitHub saying the UX for long tasks feels like staring at a blank wall.
But honestly, Claude Code itself streams output—it keeps working. The problem isn’t that it’s not working, it’s that it doesn’t report. Like that programmer at your company who keeps their head down and does good work but never says “I’m done with this part” in the group chat, leaving everyone unsure about project progress.
I spent about two months repeatedly testing across 30+ real projects and finally found a method to make Claude Code proactively report progress. The core is a prompt written in CLAUDE.md.
First, Let’s See the Effect: What It Looks Like After Adding This Prompt
Here’s a comparison.
Before adding the prompt, asking Claude Code to organize a project with 200+ files:
> Help me reorganize all the test files in this project by module
(Cursor blinking... long silence... suddenly a flood of output)
You waited 4 minutes with no idea what it was doing.
After adding the prompt, the same task:
> /进度 Help me reorganize all the test files in this project by module
📌 Task Breakdown (4 steps total):
1. Scan all test files, count quantity and distribution
2. Analyze existing module structure, determine target directories
3. Move files one by one and update import paths
4. Run tests to verify nothing is broken
⏳ Step 1: Scanning...
Found 47 test files across 12 directories
23 in root __tests__, 15 scattered in component directories, 9 in utils
✅ Step 1 complete. Moving to Step 2...
⏳ Step 2: Analyzing module structure...
Identified 6 core modules: auth, dashboard, payment, user, common, api
Recommended directory structure: tests/{module name}/__tests__/
The difference is obvious. You know how it plans to work, where it’s at, and what comes next.
What to Add to CLAUDE.md: The Core Prompt Recipe
Open your project’s CLAUDE.md in the root directory (create one if it doesn’t exist) and add this:
## Work Mode: Progress Reporting
When the user's instruction is prefixed with "/进度", enable progress reporting mode:
1. **Task Breakdown**: First break the task into 3-7 executable sub-steps, list them for user confirmation
2. **Step-by-Step Reporting**: After completing each step, immediately report:
- What this step did
- Key data (how many files processed, how many lines changed, what issues found)
- What comes next
3. **Report Immediately on Anomalies**: When encountering any problems or decisions needed, stop immediately and ask—don't guess
Example triggering methods:
- /进度 Organize all files
- /进度 Batch process images
- /进度 Analyze data files
That’s it. Save it, and Claude Code will automatically read it in the next conversation.
Why does it work? Because CLAUDE.md is the first file Claude Code reads on startup, like an onboarding handbook for a new intern that says “report when you work.”
Five Practical Templates Covering 80% of Your Use Cases
The generic prompt above isn’t enough. Different types of tasks need different reported information. Here are 5 templates I’ve refined through actual projects.
Template One: Batch File Processing
The most common scenario. You have Claude Code process dozens or hundreds of files and want to know which one it’s on.
## Batch File Processing Reporting Rules
When processing multiple files, report in this format:
- Before starting: list total files to process and the plan
- After every 5 files processed (or each directory completed), report current progress once
- Format: "Completed X/Y, currently processing [filename], approximately Z more to go"
- Mark failed files separately, don't skip or stop for them
I used this template to handle a legacy project code migration—200+ files from JavaScript to TypeScript. Claude Code reported every 5 files, the whole 12-minute process I knew the progress the whole time. Three files failed due to circular reference conversion, it marked them immediately, didn’t skip them silently.
Template Two: Code Refactoring
Refactoring is the operation most prone to going wrong, you need more frequent feedback.
## Code Refactoring Reporting Rules
When executing refactoring tasks:
- First step must list all affected files and functions
- Before modifying each file, explain what will change and why
- After modifying each file, explain what changed and what dependencies are affected
- If changes might break existing tests, warn in advance
This template saved me once. When refactoring a payment module, Claude Code reported as required before modifying payment-service.ts that “this file is referenced by 12 other files”—I realized the impact was much larger than I expected, and had it list all dependencies before proceeding.
Template Three: Data Analysis and Processing
The characteristic of analysis tasks is that intermediate steps are invisible, you don’t know what it saw.
## Data Analysis Reporting Rules
When analyzing data:
- First report data overview: total volume, format, quality (any null values, anomalies)
- After completing each analysis dimension, first give a one-sentence summary of key findings
- When finding anomalous data, provide specific row numbers or record IDs
- Before final conclusions, first list the analysis basis
Template Four: Environment Setup and Configuration
The scariest part of configuring environments is when something goes wrong mid-process and you don’t know.
## Environment Configuration Reporting Rules
When configuring environment or installing dependencies:
- List the complete operation checklist
- Before executing each command, explain what the command does
- After executing each command, report the result (success/failure/warning)
- When encountering version conflicts or dependency issues, provide solution options for user choice—don't decide on your own
Template Five: Debugging and Troubleshooting
During debugging, what you most want to know is “where has it checked so far.”
## Debugging Reporting Rules
When troubleshooting bugs:
- First list the investigation approach (where to start, what areas to suspect)
- After eliminating each possible cause, report the elimination reason
- When finding key clues, mark as "Key Finding"
- After narrowing down, provide conclusion and fix plan
Last time I used this template to troubleshoot a production memory leak. Claude Code followed the reporting rules and eliminated 7 possible causes step by step, the 8th was the hit—an event listener that wasn’t cleaned up. Watching its investigation felt like following a detective solving a case, the reasoning chain was tightly connected.
Advanced Technique One: Custom Commands Instead of Manual Prefix
Typing “/进度” before every instruction is a bit annoying, right? You can make it a Claude Code custom command.
Create .claude/commands/progress.md in your project root:
---
description: Execute tasks in progress reporting mode
---
Please execute the following task in progress reporting mode. Requirements:
1. First break the task into 3-7 small steps
2. Report progress and key data immediately after completing each step
3. Stop immediately to confirm when encountering exceptions
Task: $ARGUMENTS
After saving, you can use it directly in Claude Code:
/progress Refactor auth module
/progress Convert all CSS to Tailwind
$ARGUMENTS automatically replaces with what follows. This is much more convenient than manually adding a prefix every time.
Advanced Technique Two: Combine with Tasks API for Persistent Tracking
Claude Code has a built-in Tasks API starting from v2.1.16 (formerly TodoWrite). You can add a section in CLAUDE.md to link progress reporting with the task list:
## Progress Reporting Enhancement
In progress reporting mode, also use the Tasks tool:
- After task breakdown, use TaskCreate to create tasks for each step
- When starting a step, use TaskUpdate to mark it as in_progress
- When completing a step, use TaskUpdate to mark it as completed
- This way, even if the conversation is interrupted, task progress won't be lost
This solves a real pain point: Claude Code’s conversations get compressed when they’re too long, previously reported progress might be truncated. But Tasks API data is stored in the filesystem (~/.claude/tasks/), unaffected by conversation compression.
I used this approach in a large migration project that lasted 3 days. Every time I reopened Claude Code, it could pick up from where we left off through the task list, saving me from re-explaining the context.
Advanced Technique Three: Status Line Real-Time Progress Bar
Claude Code supports custom status lines—the bottom row can display anything you want. You can configure a script to show current task progress at the bottom.
Configure a status bar script in your Claude Code settings:
#!/bin/bash
# Read JSON data passed by Claude Code
read -r input
# Extract token usage from current conversation
tokens=$(echo "$input" | jq -r '.tokenUsage.total // 0')
cost=$(echo "$input" | jq -r '.cost // "0.00"')
model=$(echo "$input" | jq -r '.model // "unknown"')
echo "🔄 ${model} | Tokens: ${tokens} | Cost: \$${cost}"
Or simpler—just type /statusline in Claude Code and describe in natural language what you want to see:
/statusline Show current model name, tokens used, and cost
It will automatically generate the script and configure it for you.
The status bar doesn’t directly show task progress, but it tells you whether Claude Code is still running (token count increasing) and how much the current task cost. Combined with progress reporting mode, you get comprehensive information.
Why CLAUDE.md Prompts Can Change Claude Code’s Behavior
You might wonder, why can writing a few paragraphs in CLAUDE.md change Claude Code’s behavior?
This relates to how Claude works. When Claude Code starts, it adds CLAUDE.md content to the system prompt. The system prompt is like the AI’s “code of conduct,” weighted higher than what you say in conversation.
Think of it this way. If you tell a colleague in the group chat “say something in the group when you’re done working,” they might hear it or they might forget. But if you write this into the company’s employee handbook as “work standards,” the compliance rate is much higher. CLAUDE.md is that handbook for Claude Code.
But you can’t write just anything. Anthropic’s official recommendation is to keep effective instructions in CLAUDE.md under 150-200 items. The system prompt itself already uses about 50 items of “attention quota”—if your custom instructions are too many, Claude Code will start selectively ignoring them. Just like people, too many rules and none get remembered.
So, keep progress reporting prompts concise. Shorter is better than longer.
Pitfalls in Progress Reporting Prompts You’ve Already Fallen Into
After two months of use, here are some lessons worth sharing.
Pitfall One: Steps broken too fine，反而变慢了
My initial prompt required “report after every file processed.” What happened? Claude Code processed 200 files with 200 progress reports inserted in between—overall time doubled. Later I changed it to “report every 5 files,” and speed and information density balanced.
Finding the right reporting frequency is key. My experience: for file-level operations report every 5-10 files, for module-level operations report after completing each module, for debugging report after eliminating each possibility.
Pitfall Two: Prompt conflicts with the task
Once I wrote “stop immediately when encountering problems” in CLAUDE.md, then had Claude Code auto-fix a project with 30+ lint errors. It stopped to ask “is this okay” after every single fix—30+ times. I clicked “confirm” until my hand cramped that day.
Later I added a conditional qualifier:
Stop to confirm in these situations:
- Need to delete files
- Need to modify API interfaces
- Changes might affect more than 5 files
Handle and report yourself in these situations:
- Format fixes
- import path adjustments
- Type annotation additions
Clarifying which decisions need human input and which can be handled independently makes this prompt particularly cost-effective.
Pitfall Three: Forgot to add “don’t repeat existing context”
When Claude Code reports progress, sometimes it repeats background information already mentioned. For a 200-file task, every report would repeat “our goal is to reorganize test files.” Beyond token waste, it’s annoying to read.
Just add this to the prompt:
When reporting, don't repeat known information—only report new progress and new findings.
A Complete CLAUDE.md Configuration Example
Combining everything above, here’s my current complete configuration (progress-related part):
## Progress Reporting Mode
When instructions contain the "/进度" prefix, enable progress reporting mode:
### Basic Rules
1. First break the task into 3-7 steps, list them
2. Report immediately after each step: what was done, key data, next step
3. Don't repeat known information in reports
4. Use Tasks tool to record progress
### Autonomous Handling vs. Confirmation Boundaries
Handle and report yourself: format fixes, import adjustments, type annotations
Stop to confirm: delete files, modify interfaces, changes affecting more than 5 files
### Reporting Frequency
- File-level operations: report every 5-10 files
- Module-level operations: report after completing each module
- Debugging: report after eliminating each possibility
Less than 20 lines total, everything that needs saying is said, no废话.
One Last Thing
Claude Code is a powerful tool, but its default behavior is “work silently.” This isn’t a bug—possibly by design to avoid interrupting your workflow. But for long tasks, the experience without progress feedback is indeed poor.
This solution uses only Claude Code’s built-in features: streaming output, CLAUDE.md reading, Tasks API. No black magic—just connecting them with a prompt.
No plugins needed, no configuration changes, just add a few lines to CLAUDE.md.
If you try it and find it useful, or if you have other prompt tricks to make Claude Code smoother, let’s chat in the comments.
FAQ
Where should CLAUDE.md be placed to take effect?
Just put it in your project root. Claude Code automatically reads CLAUDE.md files in the current directory and parent directories on startup. If you want configuration to apply to all projects, you can place a global config at ~/.claude/CLAUDE.md. Project-level configuration overrides identically named rules in global configuration.
How much impact does this have on token consumption?
According to my stats, token consumption increases approximately 15-25% with progress reporting enabled. For a 200-file batch operation, without reporting it’s about 12,000 tokens, with reporting it’s 14,000-15,000. The extra tokens are worth it—you don’t have to wait in front of a black box.
Are there Claude Code version requirements?
CLAUDE.md has been supported since the earliest versions of Claude Code. Tasks API requires v2.1.16 or later (released January 2026). Custom commands and Status Line are also features that have been around for a while. Keep updated to the latest version—use claude update.