Chapter 1: Meet Claude Code

Imagine this. You have two hundred pathology reports in a folder on your desktop. Each one is a PDF or a plain text document a pathologist dictated, describing a single tumor. You need a single spreadsheet — one row per report — with the tumor size, the histologic grade, the T stage, the N stage, the margin status, and the date of the report. Your research coordinator could open each file by hand and type the fields into Excel. That’s roughly three weeks of work. Or you could do it yourself over a long weekend. Or you could open a terminal, type one word, describe the job in plain English, and watch a small program read every report, extract the fields, and produce the spreadsheet while you eat lunch.

That small program is Claude Code. This chapter is about what it is, what it can do for a clinician, and the one mental shift that makes it click.

A chatbot you can use, versus an agent that does the work

You already know what a chatbot is. You have opened ChatGPT, or Claude on the web, or Microsoft Copilot, and asked a question. You typed; it typed back. Sometimes the answer was useful, sometimes brilliant, and sometimes it confidently invented a study that does not exist. That kind of program is a chatbot — a smart conversational partner that returns words.

Claude Code is something different. Claude Code is an agent.

The word “agent” needs careful handling, because in everyday English it has the wrong connotations. An insurance agent is a person who acts on your behalf with the insurance company. A real-estate agent is a person who acts on your behalf with a seller. In software, an agent means almost the same thing: it is a program that acts on your behalf inside the computer. You describe an outcome. The agent actually goes and does it — opening files, running scripts, editing code, sending output to a CSV — instead of just describing how to do it.

🧠 Remember. A chatbot returns text. An agent returns changes — to your files, to your folders, to your spreadsheet, to your git history. That single distinction is the most important sentence in this book.

The Claude that powers Claude Code is the same Claude you may already have talked to in a browser. Same training, same model family, same way of reasoning. What is new is the body. The browser version is a brain that can only speak. Claude Code is the same brain wired to a set of hands that can touch your computer.

Where Claude Code lives

Claude Code is not a website. It is not a browser tab. It runs inside the terminal — the typing-only window we introduced in Chapter 0. If you skipped that chapter, the terminal is simply a window where you talk to your computer in text instead of clicking. On a Mac it is the Terminal app; on Windows it is PowerShell; on Linux it is whatever terminal application your distribution ships with.

You will open the terminal, navigate into the folder that holds the project you want to work on (using the cd command from Chapter 0), and then type one word — claude — and press Enter. From that moment until you exit, every English sentence you type is read and acted on by the agent.

Strictly speaking, the terminal is no longer the only place Claude Code lives. Anthropic also ships it as a desktop app for Mac and Windows, as a web app at claude.ai/code, and as extensions for the VS Code and JetBrains code editors. This book stays in the terminal anyway, on purpose: the terminal version is the original, the most complete, and the one that every advanced technique in Parts 3 and 4 assumes. Learn it here first, and the other surfaces will feel like conveniences rather than mysteries.

💡 Tip. You do not need to be fluent in the terminal to use Claude Code. You need three keystrokes. Type claude to start a session. Press Ctrl+C twice to leave a session. Type /clear to reset its memory mid-session. The rest of this book teaches you the rest at the speed you need it.

What Claude Code can actually do

Here is the concrete list of things Claude Code does, in plain language, with a clinical analogy for each:

• Reads files. Single files, whole folders, an entire project — the way a fellow might read through every chart on the service line before rounds.
• Writes files. Creates new documents, edits existing ones — the way you would draft a discharge summary in a Word document.
• Runs commands. Executes Python scripts, R analyses, SQL queries, tests, statistical packages — anything you would otherwise type into a terminal yourself.
• Searches. Finds files by name or finds text inside files — the way you might search the EMR for every progress note that mentions “neutropenic fever.”
• Looks things up online. Fetches a web page or runs a search — the way you would Google an UpToDate article during a tumor board.
• Manages version control. Saves checkpoints of your work, undoes mistakes, branches off to try something risky — the way you’d save several Word drafts named paper-v3-clean.docx, only better and more reliable.
• Chains all of the above together. Reads a script, sees an error, looks up the fix, edits the script, re-runs it, saves the result — without you typing each step.

The thing to notice is that none of this is new. These are all things you (or a colleague) were going to have to do by hand. What changes is that the typing happens for you, and the boring sequencing of small steps happens for you. Your role shifts from doing the steps to judging whether the work is good.

The eight built-in tools

When Claude Code “takes an action,” it is actually using one of a small set of built-in capabilities, called tools. The full toolbox is a little longer than what follows — there is, for instance, a Task tool that spawns helper agents, which we meet in Chapter 13 — but these eight are the ones you will see on screen most often, and the ones the rest of the book refers to by name. You do not pick the tool — the agent picks it — but you should know these names because the book and the screen will mention them.

🔧 Technical Stuff. Under the hood, each tool is a small function inside the Claude Code program. When the model “decides” to read a file, it is actually emitting a structured request that the program executes on its behalf, then feeds the result back to the model. You will rarely need to think about this until you build your own agent (Appendix B), but it explains why these same tool names show up everywhere in the book.

The deep point: you do not pick the tool. You describe the goal. The agent picks the tool, or the sequence of tools, that gets to the goal.

The mental model: describe the destination, not the route

This is the one shift that, once it clicks, makes Claude Code feel obvious. Compare two ways of asking for the same thing.

The old way sounds like writing a recipe:

Open the reports folder. Loop through every .txt file. For each one, use a regular expression to find the line that contains “Histologic Grade:”. Parse out the grade number. Append a row to a CSV with the filename and the grade.

That is fine instruction if you are teaching a junior coder. It is terrible instruction for Claude Code, because it forces a particular path.

The new way sounds like giving an order in clinic:

Extract the histologic grade from every pathology report in ./reports/ and save the result as grades.csv.

You stopped explaining how. You started describing what. Claude Code reads two or three reports, sees what the format looks like, writes the script that fits, runs it, checks the output, and tells you the result.

💡 Tip. When a task feels stuck, ask yourself: am I describing the steps or the destination? Most stuck moments are someone trying too hard to specify the steps. Step back to the destination.

A clinical walkthrough: extracting from fifty pathology reports

Let’s make this concrete with the kind of job that lands on a research coordinator’s desk every Tuesday. This is exactly the shape of what the AI Office Pathology Extraction Pipeline does in production at KHCC (Chapter 0.5 tours that pipeline and its siblings) — it reads each free-text pathology report from the silver tables, extracts a structured row (tumor size, stage, nodal status, margins, histology, grade), and writes the result to a gold table that downstream researchers query. It uses Azure OpenAI’s GPT-4.1-mini through PydanticAI to force the output into a strict schema. You can run a much smaller version of the same idea on your own laptop, on de-identified reports, in about ten minutes.

Here is the situation. You have fifty de-identified pathology reports sitting in a folder called reports, saved as plain text files. You need the histologic grade out of each one for a small retrospective cohort. The grade is usually buried in a sentence like “Tumor demonstrates moderately differentiated (Grade 2) features.” Sometimes the wording is consistent. Often it is not.

You open the terminal, navigate into the folder that contains reports, and start Claude Code:

$ cd ~/projects/grade_extraction
$ claude

After a couple of seconds, a welcome panel appears and the cursor blinks. You type, in plain English:

Read every .txt file in the reports/ folder. For each one, extract the histologic grade (1, 2, 3, or “unspecified”). Write a CSV called grades.csv with columns filename and grade. Use a short Python script. Show me the script before you run it.

What happens next, step by step:

1. Claude uses the Glob tool to list every .txt file in the folder.
2. Claude uses Read to open the first two or three reports, to see what the text actually looks like.
3. Claude uses Write to draft a short Python script and shows you the contents on screen.
4. You read the script (this is the part where being a clinician matters — you are deciding whether the logic looks clinically reasonable) and approve.
5. Claude uses Bash to run the script.
6. Claude uses Read to open grades.csv and check that it looks right.
7. Claude notices three reports where the script returned “unspecified” and uses Edit to make the pattern a little more forgiving.
8. Claude re-runs the script and reports back: 47 grades extracted cleanly, 3 reports flagged for human review, CSV saved.

You watched the work happen. You read the script before it ran. You can re-run the same script tomorrow on a hundred more reports without re-typing the prompt.

⚠️ Warning. Even on a small job like this, never run extraction against identifiable patient data on a folder that is not approved for that purpose. At KHCC, real patient data lives inside Databricks and the AI Office environment, not on a personal laptop. The agent cannot tell the difference between de-identified text and real PHI. You can.

🧠 Remember. Claude Code does not replace your judgment about what to extract, how to validate the result, or where the data is allowed to live. It replaces the typing.

Why this changes a clinician’s week

Once the agent model clicks, two halves of your work start to feel very different.

The boring half — small Python loops, file-by-file processing, spreadsheet munging, regex tuning, plotting tweaks, SQL scaffolding — collapses from hours into minutes. The kind of work that used to require an evening or a long weekend now runs while you’re in clinic.

The hard half — deciding what your cohort actually is, deciding whether an extraction is clinically valid, deciding whether the result is fit to put in front of another physician — does not change at all. That is still your job. It always will be.

💡 Tip. The clinicians and pharmacists who get the most out of Claude Code are not the strongest coders. They are the ones who can most clearly describe what they want. If you can write a coherent methods section, you can drive this tool.

Try This

Open a terminal in any folder on your computer that contains a handful of plain text files — your notes folder works fine. Type claude and press Enter. When the cursor appears, ask:

List every file in this directory, then tell me which one is the longest by line count.

Watch what happens. Notice that you did not pick the tool. Claude used Glob to find the files, then either Read or Bash to count lines, then summarized the result in plain English. You described a goal. Claude built the route.

When it finishes, press Ctrl+C twice to exit.

Watch Out

Do not open Claude Code, type “Build me a clinical dashboard,” and judge the tool by what you get back. That is not a prompt. It is a project. Claude will produce something, and it will be the wrong something, and you will conclude the whole idea is overhyped.

Start small. One folder. One job. One file as output. Build trust with the agent on something whose right answer you already know, before you ask it for something whose answer you don’t. The book is built that way on purpose: every chapter from here on adds exactly one new idea on top of what you already know.