doc: writer - fs cloaude

3-drafting/claude-virtual-filesystem-guide.md

@@ -2,9 +2,10 @@
 slug: claude-virtual-filesystem-guide
 title: "Inside Claude's Sandbox: What Happens When Claude Creates a File"
 author: henry
-status: outline
+status: drafting
 created: 2024-12-25
-updated: 2026-01-06
+updated: 2026-01-07
+revised: 2026-01-07
 content_type: debugging-story
 
 primary_keyword: "claude file creation"
@@ -647,3 +648,214 @@ This article is a technical tutorial/debugging-story based on personal investiga
    - Claude удивлён — он не видит команду изменения в истории Tab 1
 
    → Демонстрирует, что sandbox — общий для всех сессий одного чата
+
+---
+
+# Draft
+
+Did you know that every Claude conversation runs in its own sandbox container with a real filesystem? Understanding how Claude creates, stores, and manages files gives you a significant advantage when working with this AI. This is the hidden machinery that determines whether your generated files survive or vanish.
+
+Let me show you what's actually happening under the hood.
+
+**Note:** File creation requires a paid plan (Pro, Max, Team, or Enterprise). Free users only have access to Artifacts.
+
+## The Filesystem Structure
+
+Here's the thing about Claude's sandbox: it's a proper Ubuntu container with a defined directory structure. Knowing these paths saves debugging time.
+
+| Path | Contents | Persistence |
+|------|----------|-------------|
+| `/mnt/user-data/uploads/` | Files you upload to the chat | Persistent |
+| `/mnt/user-data/outputs/` | Downloadable files visible in sidebar | Persistent |
+| `/home/claude/` | Claude's working directory | ⚠️ No guarantee |
+| `/mnt/skills/` | Built-in capabilities and instructions | Read-only |
+
+You can explore this yourself:
+
+```
+view /mnt/user-data/
+```
+
+The critical distinction: files in `/mnt/user-data/` persist across sessions. Files in `/home/claude/` might disappear when the container times out.
+
+> **Pro tip:** Files in `/home/claude/` can still be opened in the sidebar — click the filename in Claude's tool output (when it creates or edits a file). But they won't appear in the sidebar's file list until moved to outputs.
+
+## What Happens When Claude Creates a File
+
+When you ask Claude to create a file, it follows a two-step process. First, Claude creates the file in `/home/claude/`. Then, after finishing work on it, Claude copies it to `/mnt/user-data/outputs/` using a tool called `present_files`.
+
+Here's where it gets interesting: after this process, there are TWO copies of your file. One in Claude's working directory, one in outputs. This duplication is the source of most confusion around file management.
+
+## Common Problems and How to Solve Them
+
+In simple scenarios, Claude handles files well. But in longer conversations with multiple file operations, things can go sideways. The most common issues are: Claude created a file but didn't copy it to outputs (invisible file), Claude edited the version in `/home/claude/` instead of `/mnt/user-data/outputs/` (changes don't appear), and confusion about which files you shared during the conversation.
+
+Don't panic. Once you understand the filesystem layout, fixing these is straightforward.
+
+## Walkthrough: The File Lifecycle in Action
+
+Let me demonstrate with a real example. We'll build a news compilation document and watch exactly how Claude handles the file through multiple edits.
+
+### Creating an Internal File
+
+I started a conversation with this prompt:
+
+```
+Your task is to find and compile AI news into a single markdown document. 
+
+Workflow:
+1. I give you a topic or search query
+2. You search, find relevant news, select the best match, append to document
+3. We repeat until I say "done"
+4. You show me the complete document for final review
+
+Rules:
+- One news item per search
+- All items go into the same file (append, don't overwrite)
+- Include: headline, source, date, 2-3 sentence summary
+
+Search for: the funniest AI news from the last two months
+```
+
+![Claude creates internal file](screenshots/s1.png)
+
+Notice: I deliberately didn't specify where to create the file. Moreover, I hinted to Claude that work on the file would continue through my subsequent requests — this pushes it toward working with an internal file. In practice, this is a common scenario: Claude works with files internally without showing them to the user until completion. As a result, Claude created `ai-news-compilation.md` in `/home/claude/`. The file is NOT visible in the sidebar.
+
+### Appending Content
+
+I continued with another request:
+
+```
+Now find the most important news about AI image generation
+```
+
+![Appending with str_replace](screenshots/s2.png)
+
+Claude uses `str_replace` to append content. The file still isn't in the sidebar — it's an internal working file.
+
+### Viewing Internal Files
+
+What if I want to see the contents? Click the filename in Claude's tool output.
+
+![Clickable filename in tool output](screenshots/s3.png)
+
+The file opens in the sidebar preview panel:
+
+![File preview open](screenshots/s4.png)
+
+But notice: it's a preview, not an entry in the file list. This file is still in `/home/claude/` and could disappear.
+
+### Moving to Outputs
+
+To make the file persistent and downloadable:
+
+```
+move this file to /mnt/user-data/outputs/
+```
+
+![File moved to outputs](screenshots/s5.png)
+
+Claude runs `mv /home/claude/ai-news-compilation.md /mnt/user-data/outputs/`. Now it appears in the sidebar's file list. Since we moved (not copied), there's only ONE file to work with. Clean.
+
+### The "Wrong File" Problem
+
+Let's test another scenario. We'll start a new conversation with the same initial request for news compilation. This time, let's see what happens when Claude uses `present_files`.
+
+I added a few news items, and here's where things break down:
+
+```
+Find the most performant AI coding agent released in the last two months
+```
+
+![Wrong file edited](screenshots/s7-wrong-file-edited.png)
+
+What happened? Claude edited a file in `/home/claude/` — not the one in `/mnt/user-data/outputs/`. If `present_files` was used earlier, both locations have the file. Claude picked the working copy.
+
+The sidebar shows the old version. The new content exists only in `/home/claude/`.
+
+### The Fix
+
+Simple solution:
+
+```
+move this file from /home/claude to /mnt/user-data/outputs/ (override the existing file)
+```
+
+![Fix applied](screenshots/s8.png)
+
+The updated file overwrites the old one. Sidebar now shows all content including the latest addition.
+
+### Summary
+
+What we learned: Claude creates working files in `/home/claude/` by default. Files only appear in sidebar when in `/mnt/user-data/outputs/`. The `present_files` tool creates a copy, resulting in two files. Claude may edit the "wrong" file when duplicates exist. Solution: explicitly move or copy to outputs when needed.
+
+## Quick Reference: Tools and Commands
+
+Claude uses these tools internally: `view` for reading files and directories, `str_replace` for editing content, `create_file` for new files, `bash_tool` for shell commands, and `present_files` for making files downloadable.
+
+You interact with natural language. Try these prompts:
+
+- "Show me what's in /mnt/user-data/" — triggers view
+- "Create a file test.txt with 'hello world'" — triggers create_file
+- "Run `ls -la /home/claude/`" — triggers bash
+- "Copy test.txt to /mnt/user-data/outputs/" — triggers bash with cp
+- "Show me the file for download" — triggers present_files
+
+Tool names are implementation details. Claude picks the right one automatically.
+
+## Why This Matters: Filesystem MCP
+
+Understanding the internal filesystem becomes especially important when you connect Filesystem MCP — one of the most common setups for serious work with Claude Desktop.
+
+Filesystem MCP gives Claude access to your local disk. True persistence, files land directly in your project directory, ready for version control. Downside: requires setup and only works in Claude Desktop (not the web interface).
+
+But here's the catch. Adding MCP complicates the system: it's no longer enough to say "create a file" or "copy file to folder." You need to be more precise with your commands and clarify which filesystem you mean — the internal sandbox or your local disk via MCP.
+
+Use sandbox for quick explorations. Use MCP for serious projects where files need to persist.
+
+The most productive approach — edit files with Claude in its sandbox, then save them to disk:
+
+```
+read (Filesystem MCP) → edit (sandbox) → write (Filesystem MCP)
+```
+
+## Bonus: The Two-Tab Experiment
+
+Let's have some fun to wrap up, and also confirm that we have access to the same container when opening the same chat in different tabs or in Claude Desktop.
+
+Try this:
+
+**Tab 1:**
+```
+Create a file `/home/claude/test.txt` with a content "hello world"
+```
+
+**Tab 2** (same chat):
+```
+Change the file content to "hello claude"
+```
+
+![Changing file from second tab](screenshots/s9-change-the-file.png)
+
+**Tab 1:**
+```
+output the content of that file
+```
+
+The content is "hello claude". Claude in Tab 1 is confused — it doesn't see the modification command in its conversation history, but the file has changed.
+
+This confirms: the sandbox container is shared across all sessions of the same chat. The filesystem is consistent, even if conversation history isn't.
+
+## What's Next
+
+You now know where Claude keeps its files and how to control their persistence. The sandbox isn't mysterious once you understand the `/home/claude/` vs `/mnt/user-data/outputs/` distinction.
+
+Go explore your own sandbox. Run `view /` and poke around. Understand the environment you're working in.
+
+Feel more confident and take control of your workflow.
+
+---
+
+# Review Chat
+
+*(empty — waiting for review)*