Under the Hood: How Claude Desktop and Claude Code Actually Work

Purpose: Minimum necessary understanding for a researcher to use these tools confidently and without confusion. Not a technical deep-dive — a mental model that explains the behaviour you observe.

1. Claude is a text-in, text-out machine

At its core, Claude is a large language model (LLM). It takes text as input and produces text as output. "Text" here is broad — it includes the content of PDFs, spreadsheets, images (Claude can read images), and code. But fundamentally: everything goes in as text, everything comes out as text.

Claude does not browse the internet on its own, does not remember yesterday's conversation, does not have opinions about you, and does not learn from your conversations. It is a very powerful text transformation engine.

2. The context window: Claude's working memory

The single most important concept to understand is the context window.

The context window is everything Claude can "see" at once in a conversation — your messages, its own responses, any files you attached, any instructions given at the start. It is Claude's entire working memory for that session.

Think of it like a very large sheet of paper. Everything written on that sheet is what Claude knows. When the sheet is full, older content falls off. When the conversation ends, the sheet is thrown away.

Practical implications:

Typical context window sizes (2025): Claude can hold roughly 200,000 tokens — approximately 150,000 words, or a short novel. This sounds large. In practice, a folder of 20 dense PDFs will fill it.

3. Claude Desktop: you and Claude, alone

Claude Desktop is a graphical chat interface to Claude. The architecture is simple:

You → [type message, attach files] → Claude → [response in chat]

What goes into the context:

What does NOT happen:

Claude Desktop Projects add one layer: you can attach files and custom instructions to a Project, and they are prepended to every conversation in that Project. This partially solves the persistence problem, but files are still copies uploaded to Anthropic's servers, not live access to your disk.

4. Claude Code: Claude with tools

Claude Code is a different architecture. Claude is still the same model — but now it has tools it can use.

You → [type message in terminal] → Claude thinks → uses a tool → sees result → thinks → responds

Tools available by default in Claude Code:

This is the key difference. Claude Code's Claude is not just talking to you — it is an agent that can act on your computer. It can read your files without you uploading them. It can write results directly to disk. It can run a Python script to process 1000 rows of data.

The agent loop

When you give Claude Code a task, it does not just respond once. It runs a loop:

  1. Think — what is the task? what do I need?
  2. Act — use a tool (read a file, run a command, search the web...)
  3. Observe — see the tool's output
  4. Think again — what did I learn? what next?
  5. Repeat until the task is done, then respond to you

You can watch this happen in real time in the terminal — Claude Code shows you each tool use as it happens. This transparency is useful: you can see what it is doing and why.

The agentic loop: Your prompt leads to Claude gathering context, taking action, verifying results, and repeating until the task is complete. You can interrupt at any point.

Diagram: the agentic loop. Source: How Claude Code works — official Claude Code documentation (Anthropic).

What stays local, what travels

The agent loop diagram above shows the logical flow but not the data boundary. Here is what actually crosses the network:

What stays on your machine vs. what is sent to Anthropic: tool execution is local, but file contents travel in the API call.

Diagram: local execution vs. Anthropic servers. The key point: files are read locally by tools, but their contents are assembled into the context payload and sent to Anthropic's API on every loop turn. "Local" means the files are not uploaded as files — it does not mean the content is private. → See A.issue.privacy-security for GDPR implications, training data policies, and the personal data decision flowchart.

5. MCP: plugging in external tools

MCP (Model Context Protocol) is a standard that lets you connect Claude to external services and tools beyond the defaults.

Think of MCP servers as plugins for Claude Code (and increasingly for Claude Desktop too). Examples:

MCP servers are small programs that run on your computer and expose their functionality to Claude. You configure which ones Claude has access to. Claude then decides when to use them.

This is how the Zotero integration works: a running MCP server translates Claude's requests ("search for papers on X") into Zotero API calls, and returns the results to Claude's context.

6. The system prompt: invisible instructions

Every Claude conversation begins with a system prompt — a block of instructions that sets Claude's behaviour, role, and constraints. You usually do not see it, but it is always there.

In Claude Desktop, the system prompt includes Anthropic's default safety and behaviour instructions, plus any custom instructions you set in settings or in a Project.

In Claude Code, the system prompt includes Anthropic's defaults plus the contents of a special file: CLAUDE.md — a markdown file you place in your project folder. If this file exists, Claude Code reads it at the start of every session. This is how you give Claude persistent context about your project, your preferences, and your workflow — without re-typing it every time.

Example CLAUDE.md contents for a researcher:

# Project: Inquisition Sources 1230–1320

I am a historian working on inquisition records from Languedoc.
Key concepts: perfecti, credentes, deposition testimony, notarial formula.
Output language: English unless I specify otherwise.
When extracting data, output as CSV unless I say otherwise.
My Zotero library covers this period — use it when I ask for sources.

7. What this means practically

Question Desktop Code
Can Claude see my files without uploading? No Yes
Does Claude remember last session? No No (but CLAUDE.md persists)
Can Claude write to my disk? No Yes
Can Claude process a whole folder? No Yes
Can Claude connect to Zotero? With plugin With MCP server
Do I need to code to use it? No No (mostly)
What happens when context fills up? Older messages drop off Same

8. What you do NOT need to understand

For the purposes of this workshop, you do not need to know:

The mental model above — context window, agent loop, tools, CLAUDE.md — is sufficient to use Claude Code effectively and to understand why it behaves as it does.

Related