Chapter 01 · Section III · 12 min read
Working directory, files, and shell
Claude Code inherits the directory you launched it from as its workspace. Understanding what that scope is — and how git awareness, file paths, and shell commands sit inside it — is the whole ergonomic story.
The moment you type claude in a directory, that directory becomes the session’s workspace. File tools resolve paths against it. Shell commands run inside it. Everything Claude sees, at least by default, is scoped there. That single fact carries most of what you need to know about using Claude Code well.
The working directory is the map
If you launch Claude Code from ~/projects/aln, then in the transcript you can write:
open src/pages/index.astro…and it will resolve as ~/projects/aln/src/pages/index.astro. Absolute paths also work if you need to reach outside the workspace, but Claude will usually ask before doing that — reading /etc/passwd on a whim is not something it does silently.
Git awareness is built in
If the working directory is inside a Git repository, Claude picks up on that. It can:
- Read
git status,git diff,git logwithout extra hand-holding. - Understand which files are staged versus modified versus untracked.
- Notice when you have uncommitted work before proposing something destructive.
You do not have to tell it “this is a Git repo.” It will figure it out on its own the first time it needs to.
Files: three tools, three roles
Three file tools cover essentially all read-write work:
Read— pull a file (or a slice of one) into the conversation. Text files, PDFs, images, notebooks.Write— create a new file, or replace an existing one wholesale. Prefer Edit for existing files.Edit— make an exact string replacement inside an existing file. Fails safely if the target string is not unique.
The next chapter has a whole section on picking between them; for now, know that these three exist.
The shell is the escape hatch
Anything Claude cannot do with the built-in tools, it does with Bash. That includes running your tests, invoking git, calling out to curl, starting a background process, and so on. Shell commands run in the same working directory, and — depending on your permission mode — they usually prompt you for approval before executing.
Multiple working directories
You can tell Claude Code about additional directories at launch time. Handy for monorepos where a task spans, say, apps/web and packages/ui. The session’s “map” then covers all of them.
Check your understanding
Quick check
—