The Quick Answer

Reference files in Claude Code using @filename syntax with tab completion for quick access. Hold Shift while dragging files to create references instead of opening them. Use @/path/to/file for nested files and include frequently referenced paths in your CLAUDE.md to preserve context across sessions.

Getting Started with @ References

The @ reference syntax is one of Claude Code's most powerful features for efficient file management. It allows you to quickly add a file's content to the context without Claude having to find and read the file itself, which usually takes longer.

Basic @ Reference Syntax

Type @ followed by the filename to reference any file in your project:

@package.json
@src/components/Header.tsx
@README.md

Pro tip: Use tab completion after typing @ to quickly navigate and select files. This saves typing and prevents path errors.

Three Ways to Reference Code

1. Reference the file by path

   • Type @ and start typing the filename
   • Press Tab to autocomplete
   • Works for any file in your workspace

2. Paste into Claude Code

   • Copy the entire files contents
   • Paste into Claude Code
   • Shows as "[Pasted text #1 +100 lines]"

3. Reference the file in plaintext

   • Just say where the file is located
   • Claude Code will usually try to find the file
   • E.g. "Look at my models.py file inside of the root of my project"

Common Scenarios and Solutions

Referencing Multiple Related Files

When working with interconnected files, reference them all at once to give Claude complete context:

$> I need to update the user authentication flow. Here are the relevant files:
$@src/auth/login.ts
$@src/auth/register.ts
$@src/middleware/auth.ts
$@src/types/user.d.ts

Working with Nested Directories

For deeply nested files, use the full relative path:

$@src/components/dashboard/widgets/ChartWidget.tsx
$@tests/unit/services/auth/login.test.ts

Referencing Files in CLAUDE.md

Include frequently used files in your CLAUDE.md for automatic context:

# Project Structure
Key files for reference:
@src/config/database.ts - Database configuration
@src/utils/helpers.ts - Common utility functions
@docs/API.md - API documentation

This ensures Claude always has access to critical files without manual referencing each session.

Best Practices for Efficient Referencing

1. Group Related Files

Instead of referencing files one by one as you work, group all related files upfront:

Less efficient:

> Update the header component @src/components/Header.tsx

...

> Now update the styles @src/styles/header.css

...

> Also need to update the test @tests/Header.test.tsx
...

More efficient:

> Update the header component with new navigation. Files:
@src/components/Header.tsx
@src/styles/header.css
@tests/Header.test.tsx
@src/types/navigation.d.ts

2. Use Descriptive Context with References

Don't just list files - explain their relationship:

> I'm refactoring the payment processing. The current flow is in:
@src/services/payment.ts (main logic)
@src/api/stripe.ts (payment provider integration)
@src/models/Transaction.ts (data model)

The new architecture should separate concerns better.

3. Reference Before Requesting Changes

Always reference files before asking for modifications:

Do this:

> @src/components/Button.tsx
Add a loading state to this button component

Not this:

> Add a loading state to the button component

4. Clean Up Stale References

Use /clear between unrelated tasks to avoid confusion:

> /clear

> Starting new task: Update user profile. Files:
@src/pages/profile.tsx
@src/api/user.ts

Tips & Tricks

Quick Reference Shortcuts

• Recent files: Claude remembers recently referenced files in the session
• Wildcard-like behavior: @Button might find Button.tsx, Button.test.tsx, etc.
• Case sensitivity: File references are case-sensitive on Linux/Mac

Image and Asset References

Images work differently - use Control+V (not Cmd+V on Mac) or drag and drop:

$[Drag image here]
$> Update the logo in @src/assets/logo.svg to match this design

Managing Large Files

For large files, reference specific sections:

$@package.json - specifically the "scripts" section needs updating
$@src/config/webpack.config.js - focus on the loader configuration

Cross-Repository References

When working with monorepos or multiple related projects:

> Compare the auth implementation:
@packages/web/src/auth/login.ts
@packages/mobile/src/auth/login.ts

Troubleshooting Common Issues

References Not Working

Symptom: @ symbol doesn't trigger dropdown

Fix:

1. Ensure you're in a Claude Code session (not web interface)
2. Check if file exists in current workspace
3. Try restarting Claude Code

Context Overflow

Symptom: "Context limit reached" when referencing many files

Solutions:

1. Use /compact to summarize conversation or /clear to clear it entirely
2. Reference only changed sections
3. Clear context between major tasks