The Harness — AI Education

What Happens When You Open a Session

When you launch Claude Code in a project, something happens before you type a single word. Claude checks what it is connected to. It reads your CLAUDE.md (Lesson 4). It loads your MCP servers (Lesson 8). It discovers available skills. It inventories its built-in tools. It scans the codebase structure.

That entire connection layer (the thing that wires Claude to your project, your tools, your APIs, and your custom behaviors) is called the harness.

The model reasons. The harness acts.

The Model vs. The Harness

This distinction is important and often misunderstood.

Claude (the model) is the brain. It reads text, thinks about it, and decides what to do next. It is the same Claude whether you use it in a chat window, in an API call, or in Claude Code.

The harness is everything surrounding the model that lets it act on the real world. It provides the tools (read files, write files, run commands, search code). It manages permissions (what Claude is and is not allowed to do). It handles context (compressing old conversation to fit the context window). It connects MCP servers. It loads skills.

Without the harness, Claude is a brain in a jar. Smart, but unable to touch anything. The harness gives it hands.

Key insight

When you open a session and see Claude "checking the harness for this repo," it is discovering what it is connected to. Which MCP servers are active? Which skills are available? What does the CLAUDE.md say? The harness is the inventory of everything Claude can reach and do in this specific project.

What the Harness Connects

The harness ties together five categories of capability:

1. Built-in tools. Read files, write files, edit files, search by pattern, search by content, run shell commands. These are always available. They are how Claude interacts with your codebase and your computer.

2. MCP servers. External tool connections you have installed (Lesson 8). Each one adds new tools to Claude's repertoire: project management actions, email operations, database queries, whatever the MCP provides.

3. Skills. Custom instruction sets (Lesson 10) that teach Claude specific workflows. A skill might define how to deploy, how to review code, how to generate a report. Skills are loaded from your project or your global configuration.

4. CLAUDE.md. Your project's persistent context (Lesson 4). The harness reads it at the start of every session to give Claude project-specific knowledge.

5. The codebase itself. The files, folders, git history, and structure of whatever project you are working in. Claude can read any file, search any pattern, and understand the full context of your code.

Together, these five things define what Claude can see, what it knows, and what it can do in any given session. Different projects have different harnesses. One project might have three MCP servers and a dozen skills, while another might have just a CLAUDE.md and the built-in tools.

What the harness connects

Claude

Click any node to see examples

The Agentic Loop

The harness powers a simple loop that runs every time Claude takes action:

1. Gather context. Claude reads files, checks the CLAUDE.md, queries MCP servers. Whatever it needs to understand the current state.

2. Take action. Claude edits a file, runs a command, calls an MCP tool, creates a new file. Whatever the task requires.

3. Verify results. Claude checks whether the action worked. Did the build pass? Did the test succeed? Did the API return the expected data?

4. Repeat. If something failed, Claude reads the error and tries again. If it succeeded, it moves to the next step. This loop continues until the task is done or Claude needs your input.

This is why Claude Code feels different from a chat. It is not generating a response and stopping. It is executing a loop: reading, acting, checking, adjusting, over and over until the work is done.

Real-world example

When you say "add a contact form to the website," Claude does not just write code and hand it to you. It reads the existing site structure (gather context), writes the form component (take action), runs the build to check for errors (verify), fixes any type errors it finds (repeat), runs it again until it compiles clean, then tells you it is done. That entire cycle is the agentic loop powered by the harness.

Slash Commands: Talking to the Harness

Claude Code has built-in slash commands that let you interact with the harness directly. These are not prompts to the model. They are instructions to the infrastructure around it.

/init generates a CLAUDE.md for the current project. The harness scans your codebase and creates the context file.

/mcp shows which MCP servers are connected and what tools they provide. This is your view into what external capabilities Claude has in this session.

/clear resets the conversation context. The harness wipes the current conversation but keeps the CLAUDE.md and MCP connections intact.

/resume reloads context from the previous session. The harness reads the saved conversation and picks up where you left off.

/usage shows how many tokens you have used in this session and your billing status. Useful for keeping track of costs.

/remote runs a Claude Code session on a remote server instead of your local machine. Useful for heavy tasks or when you want work to continue while your laptop sleeps.

Key insight

Slash commands talk to the harness, not the model. When you type /init, Claude (the model) does not decide what to do. The harness runs a specific procedure to scan your project and generate the file. The distinction matters because slash commands are deterministic: they do the same thing every time, regardless of conversation context.

Slash Commands Reference

Why This Matters

The harness is why Claude Code is more than "ChatGPT in a terminal." A chat model can only read your message and generate a response. Claude Code, through the harness, can:

Read and write actual files on your computer
Run shell commands and see the output
Connect to external services through MCP
Follow custom workflows defined in skills
Remember project context through CLAUDE.md
Verify its own work by running builds and tests

The model provides the intelligence. The harness provides the reach. Together, they form an agent that can do real work, not just talk about doing it.

Understanding the harness helps you debug problems. If Claude cannot find a file, it is a harness issue (file paths, permissions). If Claude does not know how to use an API, it is an MCP issue (install the right server). If Claude forgets your project conventions, it is a CLAUDE.md issue (update the file). Knowing where the problem lives tells you where the fix is.