How to Do File Uploads on Claude Code

Claude Code doesn't have a traditional "upload" button, but it gives developers several precise ways to feed files, images, and structured data directly into a conversation. The right method depends on whether you're passing source code, images, PDFs, or large directory trees. Below is a practical breakdown for developers who need to stay in flow without constantly copy-pasting content.

• Who it's for: Developers using Claude Code on macOS/Linux who need to share local files as context.
• Key trade-off: Every file you add consumes tokens from your session window, so large or binary files can burn through your usage allowance fast.
• Data point: Claude's context window supports up to 200,000 tokens, but a single large PDF or image can easily use thousands of tokens.
• Tool tip: Usagebar shows your live Claude Code usage in the macOS menu bar so you know exactly how much headroom you have before adding heavy file context.

What "file upload" actually means in Claude Code

Claude Code is a terminal-based agentic tool, not a chat UI. Instead of a drag-and-drop file picker, it exposes file context through three main mechanisms: reading files from disk directly, piping content via stdin, and referencing paths in your prompt. Understanding which mechanism to use prevents the most common frustration: silently hitting your usage limit mid-task while Claude is knee-deep in a large refactor.

How to reference local files in your Claude Code prompt

The simplest way to give Claude Code access to a file is to mention its path in your prompt. Claude Code can read files from your working directory autonomously when you describe the task clearly.

claude "Read ./src/api/upload.ts and explain the multipart handler"

Claude Code will call its built-in Read tool, fetch the file contents, and include them as context. This works for any plain-text file: TypeScript, Python, YAML, Markdown, SQL, and so on. According to Anthropic's Claude Code documentation, the tool has direct filesystem access within the project directory by default.

Reading multiple files at once

You can ask Claude Code to read several files in a single turn:

claude "Compare ./src/models/user.ts and ./src/models/account.ts and identify shared fields"

Claude Code will parallelize the reads internally. Keep in mind that each file's content lands in the context window, so reading ten large files at once can trigger usage warnings quickly.

How to pipe file content via stdin

For one-off file inspection or when you want precise control over what gets passed, use stdin piping:

cat ./logs/error.log | claude "Summarize the most frequent errors"

Or with a flag for non-interactive mode (useful in CI pipelines):

cat ./schema.sql | claude -p "Generate TypeScript types from this schema"

The -p flag runs Claude Code in print mode, outputs the response, and exits. This is the most token-efficient approach for single-file tasks because you control exactly what enters the context.

How to upload images and screenshots to Claude Code

Claude Code supports vision. You can pass images using the --image flag (or drag-and-drop into some terminal emulators that support iTerm2-style inline images):

claude --image ./screenshots/figma-mockup.png "Implement this layout in Tailwind CSS"

This is particularly useful for:

• Passing Figma screenshots for component scaffolding
• Sharing error screenshots from a browser or Xcode
• Providing a database diagram (ERD) for schema generation
• Uploading a hand-drawn wireframe for rapid prototyping

Images consume a substantial chunk of tokens (a 1024x768 screenshot can use 800-1,500 tokens depending on detail). If you're working toward a usage limit, this is where unexpected context spikes happen.

Passing images inline during an interactive session

Inside an active Claude Code session, you can reference an image path directly in your message:

@./assets/current-ui.png Fix the spacing issue visible in this screenshot

Claude Code's @ file mention syntax works for images as well as source files.

How to give Claude Code access to an entire directory

For larger refactors or codebase-wide tasks, you don't need to upload files manually. Claude Code indexes your project via its Glob and directory-tree tools. Launch it from your project root and it will navigate the file tree autonomously:

cd /your/project
claude "Audit all API route handlers for missing input validation"

To scope the context and reduce token usage, use --add-dir to include a specific subdirectory or restrict access:

claude --add-dir ./src/api "Refactor all handlers to use the new middleware signature"

This is especially important on Pro plans where the Claude Code usage affects your Pro limits. Scoping to a subdirectory rather than the full monorepo can dramatically cut token consumption.

How to use the /read slash command inside a session

During an interactive session, the built-in file reading is available through natural language, but you can also be explicit:

> Read ./config/database.yml and tell me what connection pool settings are configured

Claude Code will invoke its Read tool and show you the file path and line range it consumed. This transparency helps you gauge context usage in real time. For a full reference of available session commands, see the Claude Code slash commands guide.

How file uploads affect your Claude Code usage limits

Every file you pass to Claude Code, whether via path reference, stdin, or image flag, is tokenized and counted against your session's usage window. This has two practical implications:

• Large files can silently eat your allowance. A 500-line TypeScript file might cost 2,000-3,000 tokens. Passing 20 of them in a session adds up fast.
• Usage windows reset on a rolling basis. Knowing exactly when your window resets helps you plan heavy file-context tasks. The Claude Code usage reset schedule explains the timing.

The worst scenario: you're wrapping up a PR, you paste a large file for a final review, and Claude Code hits the limit. You're locked out for up to 5 hours at the worst possible moment.

Monitor usage while working with large files

Usagebar sits in your macOS menu bar and shows live Claude Code token usage with smart alerts at 50%, 75%, and 90% of your limit. When you're about to paste a large schema file or a batch of screenshots, you can glance at the menu bar and know whether you have the headroom. Credentials are stored securely in macOS Keychain. It's pay-what-you-want, with a free tier for students.

You can also check your current usage with the /usage command inside any Claude Code session, or at claude.ai/settings/usage.

Tips for reducing token cost when sharing files

• Trim before passing: Use head -n 100 ./file.ts | claude "..." to pass only the relevant portion of a large file.
• Use grep to extract relevant sections: grep -A 10 "function uploadHandler" ./routes.ts | claude "..."
• Compress images before passing: Scale screenshots to 50% before using --image to cut vision token cost.
• Scope directories explicitly: Use --add-dir to limit Claude Code's reach to the relevant package or service.
• Avoid re-reading files Claude already saw: Within a session, Claude Code retains previous file reads in context; re-mentioning the same file doesn't always require re-reading it.

For a broader strategy on keeping token consumption in check, see the guide on how to reduce Claude Code token usage.

Key takeaways

1. Reference files by path in your prompt: Claude Code reads them autonomously using its Read tool.
2. Pipe content via cat file | claude "..." for precise, single-file control.
3. Use --image ./path.png for screenshots, diagrams, and visual context.
4. Use --add-dir to scope large projects and avoid burning tokens on irrelevant files.
5. Monitor your usage in real time with Usagebar so a big file paste doesn't end your session early.

Sources

• Anthropic: Using Claude Code with your Pro or Max plan
• claude.ai/settings/usage
• Usagebar: How to reduce Claude Code token usage
• Usagebar: Claude Code usage statistics command
• Usagebar: When does Claude Code usage reset