claude-code - 💡(How to fix) Fix Claude Code surfaces are invisible, undocumented, and unreliable — users waste significant effort on workarounds [1 participants]

Problem

Claude Code ships across five surfaces — CLI, desktop app (Mac/Windows), VS Code extension, JetBrains plugin, and claude.ai/code. There is:

• No discovery path between them
• No concise documentation explaining what they are, how they differ, and how they interact
• No product awareness in Chat or Code to connect users to the right tool
• No onboarding that doesn't assume you're already a developer
• Reliability issues that burn user trust and drive them away from the tools

I spent approximately 80 hours building a custom framework to solve problems these shipped products already address. Neither Chat nor Code corrected course at any point.

The full experience failure

1. The tools are invisible

Chat has zero awareness of Claude Code's surfaces. The CLI never mentions the desktop app or IDE extensions. claude.ai/code sits in the navigation with no explanation of what it is or why you'd use it. The desktop app requires you to already know it exists.

2. Nothing explains them

There is no single page that answers: "What are all the ways to use Claude Code, how do they differ, how do they access files, and which one should I use?" The information is scattered across 200K+ words in the learning library. Nobody is reading that.

claude.ai/code has developer-oriented features but no plain-language explanation of what it does, how it differs from Chat, or when to use it. The entire promise of Claude is that you don't need to be a developer — but the product discovery assumes you are one.

3. When you do find them, they're unreliable

The desktop app runs sessions on VMs that crash and lose work. Once that happens, trust is burned. You stop using it. You go back to the manual path — Chat plus CLI — because at least that doesn't lose your files.

This isn't just a bug. It drives the entire user behavior pattern: avoid the tools that should help, build workarounds instead, waste time.

4. Chat actively assists the wrong direction

On March 20, 2026, I explicitly asked Chat for a complete list of Anthropic's tools and capabilities. Chat produced a ~3,500-word reference doc that included — in one buried line — that Claude Code has a web version and iOS app. No emphasis, no implications drawn.

The very next day, I built two more framework sessions with the architecture "Chat is the brain, Code is mechanical." Chat actively helped build this despite its own reference doc from the previous day effectively invalidating the approach.

This continued for ~80 hours. At no point did Chat or Code say "the thing you're building already exists as a shipped product."

Chat buried an architectural insight as a bullet point, didn't connect it to subsequent work, and then actively helped build something it had the information to challenge.

5. The result: 80 hours wasted

The full cycle:

1. Tools are invisible → user doesn't know they exist
2. Documentation is impenetrable → user can't evaluate what they find
3. The tool that's found is unreliable → user loses trust after losing work
4. User falls back to manual workarounds → Chat helps build them
5. Chat has the information to redirect but doesn't → 80 hours spent building what already ships

What needs to change

Reliability

1. VM sessions must not lose work. If the desktop app's cloud sessions crash, there must be recovery. Users who lose work once won't come back.

Documentation

1. A single, clear "How to Use Claude Code" page — all five surfaces, how they differ, how they access files, how they interact, which to choose. One page. Written for non-developers.

Onboarding & discovery

1. claude.ai/code needs a plain-language explanation visible before you click into it.
2. Chat must know about Code's surfaces and recommend them when relevant.
3. CLI first-run should provide an accessible description of all surfaces — not just "the desktop app exists" but what it does, what it gives you that the CLI doesn't (visual diffs, GUI file management, parallel sessions, PR monitoring), how it accesses your files, and when you'd choose it. Same for the IDE extensions and web app. A user who installs the CLI should walk away understanding the full landscape, not just the tool they happened to find first.
4. claude.ai needs a visible product switcher with brief descriptions.

Contextual intelligence

1. Critical information needs emphasis proportional to impact. One line in 3,500 words that changes a user's entire project direction should be flagged, not buried.
2. Chat should connect information across sessions and flag conflicts with prior work.
3. Neither Chat nor Code should help users build workarounds for shipped products without saying so immediately.

Accessibility

1. Stop assuming users are developers. The product's value proposition is enabling non-developers. Everything — discovery, docs, onboarding, error recovery — should reflect that.

Impact

80 hours of wasted development. Driven by invisible tools, impenetrable documentation, reliability issues that burned trust, and an AI assistant that had the relevant information and actively helped build in the wrong direction anyway.

If this happened to an engaged, paying user who explicitly asked for a tools overview, it is happening at scale.