diff --git a/2-outline/claude-virtual-filesystem-guide.md b/3-drafting/claude-virtual-filesystem-guide.md similarity index 72% rename from 2-outline/claude-virtual-filesystem-guide.md rename to 3-drafting/claude-virtual-filesystem-guide.md index 27ca821..b61dd9c 100644 --- a/2-outline/claude-virtual-filesystem-guide.md +++ b/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)* diff --git a/assets/claude-virtual-filesystem-guide/screenshots/s9-change-the-file.png b/assets/claude-virtual-filesystem-guide/screenshots/s9-change-the-file.png new file mode 100644 index 0000000..ad96869 Binary files /dev/null and b/assets/claude-virtual-filesystem-guide/screenshots/s9-change-the-file.png differ