Navigating Your Workspace

Learn the terminal fundamentals you need to move around your projects, explore files, and understand how Claude Code sees and interacts with your workspace.

What is a Terminal?

A terminal (also called a command line, shell, or console) is a text-based interface for interacting with your computer. Instead of clicking icons and buttons, you type commands. It might feel unfamiliar at first, but you only need a handful of commands to be productive with Claude Code.

Think of the terminal like a conversation with your computer—you type an instruction, press Enter, and the computer responds. Claude Code works the same way, except your conversation partner is an AI that can read, write, and run code.

Opening the Terminal

• macOS: Press Cmd + Space, type "Terminal", and press Enter. Or open it from Applications > Utilities > Terminal.
• Windows: Press Win + R, type cmd or wt (Windows Terminal), and press Enter.
• Linux: Press Ctrl + Alt + T on most distributions.
• VS Code: Press Ctrl + ` (backtick) to toggle the integrated terminal.

When the terminal opens, you will see a blinking cursor next to a "prompt"—something like user@machine ~ $. This is where you type commands.

Essential Navigation Commands

You only need three commands to navigate your file system confidently. These work on macOS, Linux, and Windows (in PowerShell or Git Bash).

pwd — Where Am I?

Short for "print working directory." This tells you your current location in the file system.

$ pwd
/Users/yourname/Projects/my-website

ls — What's Here?

Lists the files and folders in your current directory. Add -la to see hidden files and details.

$ ls
README.md  package.json  src/  public/  node_modules/

$ ls -la
total 48
drwxr-xr-x  8 you  staff   256 Jan 15 10:30 .
drwxr-xr-x  5 you  staff   160 Jan 10 09:00 ..
-rw-r--r--  1 you  staff   230 Jan 15 10:30 .gitignore
-rw-r--r--  1 you  staff   450 Jan 15 10:30 CLAUDE.md
-rw-r--r--  1 you  staff  1024 Jan 15 10:30 README.md
-rw-r--r--  1 you  staff   890 Jan 15 10:30 package.json
drwxr-xr-x  6 you  staff   192 Jan 15 10:30 src

cd — Go Somewhere

Short for "change directory." This is how you move between folders.

# Move into a folder
$ cd src

# Move up one level
$ cd ..

# Move to your home directory
$ cd ~

# Move to an absolute path
$ cd /Users/yourname/Projects/my-website

# Move to a deeply nested folder
$ cd src/components/ui

A common pattern: open your terminal, cd into your project folder, then launch Claude Code from there. This sets the "working directory" so Claude knows which project you are working on.

How Claude Code Sees Your Workspace

When you start Claude Code in a directory, that directory becomes Claude's workspace. Claude can see every file in this directory and its subdirectories (respecting your .gitignore rules). This is a critical concept to understand.

Claude does not automatically read every file at startup—that would be slow and expensive. Instead, Claude reads files on demand: when you ask a question, Claude intelligently decides which files to look at based on your question, file names, directory structure, and context from previous conversation turns.

The Working Directory

The directory where you run claude matters. Here is the typical workflow:

# Navigate to your project
$ cd ~/Projects/my-website

# Launch Claude Code here
$ claude

# Claude now knows:
#   - Your project root is ~/Projects/my-website
#   - It can read all files within this directory
#   - It will look for CLAUDE.md here for project context

If you launch Claude from your home directory instead, Claude will see your entire home folder—thousands of unrelated files. Always navigate to your specific project directory first.

The Visual Workspace Concept

Here is the most important mental model for working with Claude Code: Claude reads and writes your actual files. There is no sandbox, no separate environment, no copy of your project. When Claude edits a file, it is editing the real file on your disk. When Claude creates a new file, it appears in your project folder immediately.

This is what makes Claude Code so powerful—and why it earns the trust permission system. Every change Claude makes is real, visible in your editor, and tracked by Git (if your project uses version control).

What Claude Can See

• All files in your working directory and subdirectories
• File names, sizes, and directory structure
• File contents (when it chooses to read them)
• Git history, branches, and diffs (if your project uses Git)
• Terminal output from commands it runs

What Claude Cannot See

• Files outside your working directory (unless given an absolute path)
• Your screen or code editor GUI
• Browser tabs or running applications
• Environment variables (unless you share them or they are in config files)
• Files ignored by .gitignore (by default)

Navigating with Claude

You do not need to memorize terminal commands to navigate with Claude Code. You can ask Claude to explore your project for you. Here are some natural ways to do this:

> Show me the structure of this project

> What files are in the src folder?

> Find all TypeScript files that mention "authentication"

> What's the largest file in this project?

> Show me all the config files in the root directory

Claude will run the appropriate terminal commands (find,ls, grep, etc.) behind the scenes and summarize the results for you in plain language. You are having a conversation, not memorizing commands.

Try It Yourself

Practice these steps to build confidence with workspace navigation: