Known limitations
Honest overview of Claude Code's current limitations: what it can't do well, edge cases, and workarounds.
Claude Code is a powerful tool, but it has real limitations. Knowing them will save you frustration and help you get the most out of every session.
Context window
Claude Code uses a 200,000 token context window (roughly 150,000 words). That sounds huge, but in practice, this window fills up fast.
What consumes context:
- File contents read by Claude
- Conversation history
- Responses generated by Claude itself
- MCP tools called and their results
The real problem: on a project with more than 50 files, Claude can't keep everything in memory. At the end of a long session, it "forgets" what it read at the beginning.
How to work around this limit
Use /compact regularly to summarize the conversation and free up context. Structure your CLAUDE.md so that critical information is always present. Break large tasks into short, focused sessions.
Learn more: Context management and the 200K token window.
Hallucinations
Claude can make up information with confidence. This is the most serious problem with any language model, and Claude Code is no exception.
Concrete examples:
- Inventing an API or method that doesn't exist in a library
- Generating code that references a nonexistent npm package
- Claiming a file contains a particular function when it doesn't
- Citing official documentation with incorrect information
The risk: if you accept generated code without verifying it, you introduce subtle bugs that can pass unit tests (because the tests can be hallucinated too).
Golden rule
Never blindly trust generated code. Review every change, verify imports, test functions. Claude Code is an assistant, not a replacement for your technical judgment.
Code execution and system access
Claude Code can read and write files, execute shell commands, and interact with your system. But there are important limits.
What Claude Code cannot do:
- Access the internet directly (without a dedicated MCP)
- Interact with graphical interfaces (clicking, scrolling)
- Reliably launch long-running background processes
- Handle interactive sessions (like
vimorless) - Access files outside the working directory (unless explicitly configured)
What can go wrong:
- A destructive command (
rm -rf,git reset --hard) executed too quickly if you've enabled auto-accept mode - Cascading file changes that break project consistency
- Shell commands that fail silently, and Claude continues on a wrong basis
Protect yourself
Always work on a dedicated Git branch. Avoid --dangerously-skip-permissions locally. Use the permissions system to limit accessible tools.
Latency and speed
Claude Code is not instant. Every request makes a round trip to Anthropic's servers, and long responses take time to generate.
Typical observed times:
| Action | Estimated time |
|---|---|
| Simple question | 2 to 5 seconds |
| File generation | 5 to 15 seconds |
| Multi-file refactoring | 15 to 60 seconds |
| Complex task (agent, MCP) | 1 to 5 minutes |
Aggravating factors:
- Extended Thinking adds reasoning time before the response
- More powerful models (Opus) are slower than Sonnet or Haiku
- MCPs add additional network calls
- Throttling on Pro and Max plans limits requests per period
Worth noting
Latency is a deliberate trade-off. Claude Code prioritizes quality and depth of analysis over raw speed. If you need instant completions while typing, GitHub Copilot is better suited for that specific need.
Costs
Claude Code is not free, and costs can climb quickly if you're not careful.
Pricing structure (March 2026):
| Plan | Price | What you get |
|---|---|---|
| API (pay-as-you-go) | Variable | Sonnet: ~$3/M tokens input, ~$15/M output |
| Pro ($20/month) | Flat rate | Limited access, quick throttling |
| Max 5x ($100/month) | Flat rate | Comfortable use for an active dev |
| Max 20x ($200/month) | Flat rate | Intensive use, minimal throttling |
What gets expensive:
- Long sessions (accumulated context = more tokens)
- Extended Thinking (reasoning tokens billed as output)
- Premium models (Opus costs 5x more than Sonnet)
- MCPs that inject lots of data into the context
Optimize your costs
Use /cost to track your consumption in real time. Default to Sonnet for routine tasks and save Opus for complex problems. Compact often with /compact. For a detailed breakdown: Real costs of Claude Code.
Language support
Claude Code understands most popular programming languages, but its competence level varies.
Excellent (comparable to a senior dev):
- Python, TypeScript, JavaScript
- HTML, CSS, SQL
- Bash, shell scripting
Good (comparable to a mid-level dev):
- Java, C#, Go, Rust, C/C++
- Ruby, PHP, Swift, Kotlin
Adequate but limited:
- Rarer languages (Haskell, Erlang, Elixir, Clojure)
- Very recent or niche frameworks
- Proprietary DSLs
The problem: Claude Code was trained on data up to a certain date. Libraries, frameworks, or APIs released after that date are poorly known or unknown. That's where hallucinations are most frequent.
Tip for recent frameworks
Use the Context7 MCP to inject up-to-date documentation directly into the context. This significantly reduces hallucinations about recent APIs.
Reasoning limitations
Claude Code can solve complex problems, but it has blind spots.
Where it can fail:
- Subtle bugs involving race conditions or parallelism
- Performance optimizations that require real profiling
- Architectural decisions that depend on unstated business constraints
- Massive refactoring where it loses track of overall consistency
- Complex mathematics or precision numerical computations
The classic pattern: Claude Code excels at the first 80% of a task. The last 20%, the part that demands judgment, experience, or understanding of business context, remains your responsibility.
Summary
| Limitation | Severity | Workaround |
|---|---|---|
| Context window | Medium | /compact, short sessions, CLAUDE.md |
| Hallucinations | High | Systematic review, Context7, tests |
| System execution | Medium | Permissions, Git branch, cautious mode |
| Latency | Low | Right model for the task, patience |
| Costs | Variable | /cost, Sonnet by default, compacting |
| Niche languages | Medium | Context7, documentation in context |
| Complex reasoning | Medium | Extended Thinking, task decomposition |
Next steps
- Compare Claude Code with alternatives: vs GitHub Copilot and vs Cursor
- Discover situations where another tool would be a better fit: When NOT to use Claude Code
- Learn to work around limitations with better prompts: Prompting basics