Hello, thank you again for being part of our Claude Code Masterclass community. We are still growing, and I am grateful for every one of you.

This is Issue #6 of the Last Week In Claude Code series.

Last week had important updates:

• Claude Code can now draft UI designs from the CLI

• A new built-in output style cuts response verbosity

• Fork mode is now on by default: subagents inherit full conversation context

• I tested the DeepSeek Harness, an open-source Claude Code alternative

I have tested, documented, and linked everything I’ m sharing in this issue to save your time.

What Happened Last Week In Claude Code?

#1) Design Mode — Draft UI Artboards From the CLI

Version: Research Preview — v2.1.233+

Claude Code can now design your UI before it builds it.

The /design skill brings Claude Design’s artboard workflow into the CLI and Claude Code Desktop.

Give it a brief, and Claude publishes a canvas of editable artboards for you to pick from, then builds the one you choose.

What It Does

/design a few options for a developer dashboard that shows API usage , active sessions , an recent errors 

Claude generates multiple UI options and publishes them as a shareable canvas link. You pick one, tell Claude which to implement, and it builds it.

This removes the back-and-forth of describing UI in words.

What to Know

• Available on Pro, Max, Team, and Enterprise plans

• Requires v2.1.233 or later ( I tested on v2.1.234)

• Built on Claude Code artifacts

• Works in both the CLI and Claude Code Desktop

How to Use It

/design { Your description of the design you want } 

Claude prints a link to the published canvas. Open it, pick an artboard, and tell Claude which option to implement.

I shared a detailed walkthrough of /design in my latest tutorial read it here

#2) Concise Output Style — The New Way to Kill Fluff

Version: 2.1.237

Claude Code v2.1.237 introduced a built-in Concise output style that cuts the verbose reponses.

If you don't like long Claude explanations before it starts working on a task or after completion, concise mode removes that narration.

Five Built-In Output Styles

Concise is the new addition. It does the work as Default but skips all narration before and after.

How to Enable It

Option 1 — /config (project-scoped):

/config → Output style → Concise

Option 2 — Global settings (applies everywhere):

// ~/.claude/settings.json

{ "outputStyle": "Concise" }

Run /clear after enabling for the change to take effect in your current session.

Note :

Output styles load once at session start if you change a style mid-session and nothing changes until you run /clear.

Custom styles are also supported, you can create and save a Markdown file with frontmatter to:

~/.claude/output-styles/ for personal styles or .claude/output-styles/ for project-level styles shared with your team.

For Example :

---
name: API Impact
description: Frame every change in terms of its API surface effect
keep-coding-instructions: true
---
For every code change, lead with one of three labels: Breaking, Additive, or Internal.
Follow with a one-sentence summary of how the change affects API consumers.
Keep implementation detail in a separate section below.

I tested Concise mode and documented all five styles in detail — I Tried Claude Code Concise Mode (The New Way to Kill Fluff)

#3) Fork Mode On by Default — Subagents Now Inherit Your Full Context

Version: 2.1.232

Fork mode is now on by default in interactive sessions.

What Changed

Before this, when Claude spawned a subagent, it started fresh without memory of your conversation, and context from the session.

Now subagents inherit the full conversation and prompt cache from the parent session.

Start a fork with any task that needs everything discussed so far:

/subtask draft unit tests

The fork appears in the panel below your prompt. Its result arrives in your conversation when it finishes.

Subagents Claude spawns in interactive sessions now also run in the background by default.

Turn It Off

If you prefer the old behavior:

CLAUDE_CODE_FORK_SUBAGENT=0

#4) Quick Wins — @ Sessions, & Auto-Continue

@ Mention Another Session

Version: 2.1.232

Type @ in the prompt to mention another Claude session by name. Claude messages it directly with SendMessage

@my-backend-session check if the API changes break anything

Auto-Continue After Usage Limit

Desktop

When you hit your session limit in the Claude Code Desktop Code tab, a new Auto-continue when limits reset checkbox appears on the limit card.

Check it and leave the session open. The Desktop app retries the interrupted turn automatically after the limit resets and shows you the retry time.

External Models Testing & Tools

DeepSeek Harness — A Free, Fully Modular Claude Code Alternative

DeepSeek open-sourced its agent harness an open-source alternative to Claude Code that hit 170k+ stars in just a few days after launch.

It is a terminal agent that reads your codebase, runs tools, and writes code autonomously. The difference from Claude Code is that everything inside it is a replaceable plugin.

You can replace the model, sandbox, filesystem layer, shell execution, and agent loop. Claude Code is powerful but its control flow is locked.

How to Install

npx @deepseek-ai/dsh web

Or from the repo:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install && pnpm run build && pnpm dsh web

The Web UI opens at http://127.0.0.1:3080.

I tested it as a Claude Code alternative and documented the full results.

I Tried the (New) Claude Code Rival DeepSeek Harness — read the full breakdown here

You are now up to date with the latest major Claude Code updates.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Welcome back to the Claude Code Masterclass. Special thanks to all new members who have joined to support the newsletter.

In the last issue, we covered loop engineering from first principles: what a loop is, the four phases every loop runs through, and the three things that make one work in production.

We also showed all three Claude Code loop commands, /goal, /loop, and /schedule, running on real projects.

By the end of that issue, one question was left unanswered: what happens when a single loop is not enough?.

Some tasks cannot be done well by only one agent.

When your loop starts reviewing its own work, running tasks sequentially that could run in parallel, or producing control flow that you cannot audit, that loop has hit the ceiling.

In this issue, we will cover graph engineering and testing in a real project that proves the difference between a loop and a graph.

Graph Engineering

One of the most common misconceptions is that loops are replacing graphs. It’s not true that you throw away the loops when you build graphs.

The best way to understand how the two work together is one line:

A loop is a node in a graph

Each node inside a graph is still running a loop.

The graph is the structure that connects those loops, routes work between them, and manages what they pass to each other.

Loops to Graphs

Not every loop should become a graph. Most should stay as loops, but there are reasons to consider turning a loop into a graph.

1. Same agent is reviewing its own work

If the loop writes a report and then reviews in the same context, the reviewer already knows why every decision was made. You will see this as outputs that pass review but contain errors that an outside reader would immediately catch.

2. Two things could run simultaneously but must run one after the other

If the loop checks security vulnerabilities, then checks logic errors, then checks test coverage, those three checks are independent.

3. You cannot explain what the loop did without reading the entire transcript

In a graph, you can point to the diagram and explain every routing decision.

What Is a Graph?

Graph engineering is building multiple specialized agents (nodes) connected by edges, with shared structured state flowing between them, where the routing logic between nodes is explicit and readable as a diagram.

The three words: specialized, explicit, and readable.

• Specialized: each node has one job and its own clean context

• Explicit: every routing decision is defined in code or in the graph structure

• Readable: you can explain the control flow by pointing to the diagram

• Node: The unit of work that gets clean input, does one thing, produces structured output. If you cannot describe a node’s job in five words or fewer, it is doing too much.

Good node: collect_context analyze_security write_report 

Bad node: research_and_write_and_review_and_approve

• Edge: What is allowed to happen next. A fixed edge means Node A always goes to Node B. The question every edge answers: what is allowed to run after this?

• Conditional Edge: The decision point. When the output of Node A determines which node runs next, that is a conditional edge. The routing decision can be made by code (deterministic rules) or by an LLM (uncertain decisions that require reasoning).

• State Machine: The complete shape of the graph. Every node is a state the work can be in. A check at each node decides the next hop. When you draw the graph on paper, you are drawing the state machine.

• Shared State: The structured object that flows between nodes. Every node reads from it, writes its findings to it, and passes it to the next node. This is the backbone of the graph. What belongs in shared state: brief, evidence, node status, retry counts, severity, findings.

• Agent Loops: The loop engine running inside each node. Each node is not a single call. It is a small loop that discovers, plans, executes, and verifies until the node’s specific job is done. The internal loop stop condition is different from the graph routing condition.

It helps to understand the layers of AI engineering that position the graph as the outermost layer.

Five Layers of AI Engineering

Graph engineering has been evolving for the last two years.

LangGraph shipped the StateGraph pattern in 2024.

AutoGen, Google ADK, and the A2A protocol were building graph orchestration before "graph engineering" became a trend.

But what’s new :

• Parallel specialized nodes with clean contexts

• Fan-out then fan-in as a first-class architectural move

• Control flow you can draw as a diagram before writing the first prompt

Three Problems a Graph Solves

A graph is the right tool when a loop fails at one of three things. Here is each problem with its visual and its graph solution

Context Pollution

Solution

╔══════════════════════════════════════════════════════╗
║         THE GRAPH SOLUTION                           ║
╠══════════════════════════════════════════════════════╣
║                                                      ║
║  Node 1 [context: full codebase + task]              ║
║     │ writes structured findings to shared state     ║
║     ▼                                                ║
║  Node 2 [context: findings only. Never saw the code] ║
║     │ writes the report                              ║
║     ▼                                                ║
║  Node 3 [context: report only. Never saw findings or ║
║           the code. Reads cold like a stranger]      ║
║     │ catches what Node 1 missed                     ║
║     ▼                                                ║
║                   REAL REVIEW ✓                      ║
╚══════════════════════════════════════════════════════╝

Sequential vs Parallel Execution

Invisible Control Flow

Real Graph Example: Incident Intelligence System

I thought about a real graph running in Claude Code to solve one of the most common engineering problems.

Suppose it’s 2 AM, five microservices are down, and you have 1000 lines of error logs from five different services all firing at once.

A basic approach is to paste everything into Claude Code and ask it to find the root cause.

The loop version can’t handle this mess; this is the sequence

• All five service logs in one context. Service A errors mix with Service B errors

• The database errors look most severe and appear most frequently

• The loop identifies database connection pool exhaustion as the root cause.

When you fix the database, nothing improves because the database was not the problem.

What happened was this:

To build the best graph solution, you should design the graph before writing any code.

Shared State Schema

Every node reads from and writes to one structured object:

class IncidentState(TypedDict):
    raw_logs: dict          # Parser writes, everyone reads
    parsed_events: dict     # Parser writes by service name
    service_findings: dict  # Each Analyzer writes its own entry
    correlations: list      # Correlator writes
    cascade_chain: list     # Correlator writes (ordered)
    root_cause: dict        # Root Cause node writes
    severity: str           # P0, P1, or P2
    remediation: dict       # Remediation node writes
    node_trace: list        # Every node appends its execution record

The key rule: each node owns one section of state.

• Parser writes raw_logs

• Analyzers write service_findings[service_name]

• Correlator writes correlations and cascade_chain

Loop vs Graph on Claude Code Testing

I ran the same codebase through two loop vs graph agents , the project is our test project.

Claude Code Tracker a FastAPI application with JWT authentication, SQLAlchemy database layer, and a pytest test suite.

The codebase has bugs, security gaps, and code quality problems scattered across four files.

The goal for both architectures: find everything wrong with this codebase.

Claude Code Loop Session

We can test the loop version in Claude Code by running one loop to review the code which we obviously know its the same that wrote the code and it cant be objective

You are a senior code reviewer doing a full security and quality audit.

Your job has four steps and you must complete all four in order:

STEP 1 — READ THE CODEBASE
Read every file in the app/ directory. Understand the architecture,
the authentication system, the database layer, and the API endpoints.
Do not write any findings yet.

STEP 2 — FIND ALL BUGS
Go through every file again and list every bug, security vulnerability,
and code quality problem you find. Number each finding. Include the
file name, line number, severity (critical/high/medium/low), and a
one-line explanation of the problem.

STEP 3 — WRITE THE REPORT
Write a structured bug report with an executive summary, the numbered
findings grouped by severity, and a recommended fix for each one.
Save the report to a file called loop_report.md in the project root.

STEP 4 — REVIEW YOUR OWN REPORT
Read loop_report.md and check whether the report is accurate,
complete, and well-reasoned. State whether you stand by every
finding or whether you want to change anything.

When all four steps are complete, run /cost and report the total.

It produced a detailed report bit this cannot be fully trusted since it’s a self agent review.

In the loop version, one Claude Code session reads the entire codebase, identifies bugs, writes the report, and then reviews its own report.

This is how most developers use Claude Code for code review today. It is the natural single-session approach but has a fundamental problem

By the time the agent reaches the review step, it has already processed every file.

The agent knows why it included each finding and reasoning behind every severity rating. It cannot evaluate the report the way an independent reviewer agent can.

Claude Code Graph Session (Agent Teams)

The graph approach is to spawn three agents each with clean content and agent 3 reviews the report without ever seeing the code one the findings which gives it an independent review.

Setup

1. Open Claude Code

2. Navigate to your project

3. Confirm agent teams are enabled in your settings.json: “CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS”: “1”

4. Set effort to high: /effort high

Step 1 — Spawn Agent 1: The Context Gatherer

You are Agent 1: Context Gatherer.

Your only job is to read the codebase and produce a structured
summary. You must not find bugs, form opinions, or make judgments.
Only structure what you see.

Read every file in the app/ directory and produce a JSON file
called agent1_context.json with this exact structure:

{
  "project_name": "",
  "tech_stack": [],
  "file_inventory": [
    {
      "file": "",
      "purpose": "",
      "key_functions": [],
      "dependencies": []
    }
  ],
  "authentication_system": "",
  "database_layer": "",
  "api_endpoints": [],
  "external_integrations": []
}

Save agent1_context.json to the project root.
Do not write any bug findings. Do not evaluate quality.
Only document what exists.
When done say: AGENT 1 COMPLETE

Wait until you see AGENT 1 COMPLETE in the output.

Step 2 — Spawn Agent 2: The Bug Hunter

Open a NEW Claude Code session or spawn a sub-agent. Navigate to the same project folder. Use this prompt:

You are Agent 2: Bug Hunter.

You have not seen the codebase. You will receive a context
summary from Agent 1 that tells you what the project contains.
Your job is to use that context to guide a fresh read of the
codebase and find every bug, security vulnerability, and code
quality problem.

First read agent1_context.json to understand the project structure.
Then read each source file listed in the inventory.

For each problem you find, produce a structured finding:

{
  "id": 1,
  "file": "",
  "line": 0,
  "severity": "critical | high | medium | low",
  "category": "security | logic | quality | performance",
  "title": "",
  "description": "",
  "impact": ""
}

Save all findings to agent2_findings.json in the project root.
When done say: AGENT 2 COMPLETE — X findings recorded

Wait for AGENT 2 COMPLETE.

Step 3 — Spawn Agent 3: The Independent Reviewer

Open another NEW Claude Code session or spawn another sub-agent. Navigate to the same project folder. Use this prompt:

You are Agent 3: Independent Reviewer.

You have not seen the codebase. You have not seen the bug hunting
process. You are reading a completed bug report cold, the way an
external auditor would.

Read agent2_findings.json. For each finding evaluate:

1. Is the severity rating appropriate or is it over or under stated?
2. Is the description accurate and specific enough to act on?
3. Is there anything in this finding that seems wrong or questionable?
4. Are there categories of issues that appear to be missing entirely?

Produce a review file called agent3_review.json:

{
  "total_findings_reviewed": 0,
  "severity_adjustments": [],
  "questionable_findings": [],
  "missing_categories": [],
  "overall_assessment": "",
  "confidence_in_report": "high | medium | low"
}

Save agent3_review.json to the project root.
When done say: AGENT 3 COMPLETE

After all three finish, your project root should have:

• agent1_context.json — codebase map

• agent2_findings.json — bug/security findings

• agent3_review.json — independent audit of those findings

The graph version ran as three separate Claude Code sessions. Each agent saw only what it needed to see.

• Agent 1: Context Gatherer Reads every file in the codebase. Produces a structured JSON map of the architecture, endpoints, authentication system, database layer, and file inventory. Output: agent1_context.json is a precise architectural summary of the project.

• Agent 2: Bug Hunter Receives only agent1_context.json. Never sees the raw source files. Uses the architecture map to guide a fresh read of the codebase and produces structured findings

  It found 12 issues:

• Agent 3: Independent Reviewer Receives only agent2_findings.json. Never saw the codebase, architecture map and Agent 2's reasoning process.

In comparison graph approach is more independent, reliable and ideal for large codebases.

Final Thoughts

Graph engineering shows us that the benefit of using more than one agent is real.

While loops are reliable at small tasks, they cannot be relied on when you are building something that requires independent evaluation.

The Claude Code example we ran was a small demo to show what is possible. In a large production project with hundreds of files and multiple services, this approach becomes very useful.

The four missing categories Agent 3 caught in a small codebase would be multiplied in a large codebase.

The next step is to see how this works in LangGraph, because that is where graph engineering shows its true production benefits.

You define the nodes, edges, and shared state in code and the graph becomes something you can version, test, and deploy.

Resources

For this issue, these are the resources available:

• Testing Repo

• Tested Loop Templates Prompt (Members Resource Library)

Next Upcoming Masterclass Issues

The next issues in this Masterclass Series will cover:

• Claude Code Subagents Masterclass — Building your AI team

• Claude Code MCP Masterclass — Extending Claude’s capabilities

If you found this useful, do not forget to like share and subscribe for more insights. Let me know your thoughts and questions in the comments below.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Welcome back to the Claude Code Masterclass. We are still keeping the fire burning; thank you to all our new premium members who keep this going.

I am eternally grateful — thank you!

Occasionally, we will interrupt the ordered masterclass to cover new topics that require your urgent attention and in-depth understanding.

One such topic is loop engineering vs graph engineering. How does this apply in Claude Code?

Over the past few weeks, two terms appeared everywhere in the Claude Code community: loop engineering and graph engineering.

If you missed both or only half-understood one, this masterclass covers everything from first principles to a working project you can run today.

By the end of this issue, you will know:

• What loop engineering is and how to build one in Claude Code with /goal, /loop, and /schedule

• Why loops break and what the three failures are

• What graph engineering is and the six terms you need to understand it

• How to build a real graph on Claude Code using agent teams

• When to use a loop and when to build a graph

Note: This is long by design (and split into part 1 and 2) since we want to understand these concepts as we move on to our other masterclasses. You can save and come back to it later.

Loop Engineering In Claude Code

On June 30, 2026, Boris Cherny, the engineer who built Claude Code at Anthropic, said:

“I no longer prompt Claude anymore. I have loops running that prompt Claude and figure out what to do next. My job is to write loops.”

If you have used Claude Code seriously, you have already been creating loops and graphs.

• Every time you used /goal and Claude kept iterating without you, that is loop engineering

• Every time Claude spawned a sub-agent to handle a specific task, you were right at the start of graph engineering

To summarize this in one line

A loop is a node in a graph.

What is a Loop?

When you work with an LLM like Claude, the basic pattern looks like this:

Step 1: You write a prompt
Step 2: Claude returns an output
Step 3: You read the output
Step 4: If it is not what you wanted: tweak the prompt and try again

This is prompt engineering, and if you look at it carefully, you are running a loop.

You are the loop operator since in every iteration you decide what to change, send the next prompt, and evaluate the result.

This is the starting point for all of us, and the next level is to replace your input with an agent, which introduces the concept of running loops.

So,

Loop engineering is building a cycle that an agent runs autonomously, repeating until a stop condition is met.

The change here is about who operates the cycle: in prompt engineering, you operate it turn by turn, but in loop engineering, you define the cycle, and the agent operates it.

Prompt Engineering vs Loop Engineering

Every loop goes through different phases.

Four Phases Every Loop Runs Through

Every well-built loop has four phases that apply whether you are fixing a bug, writing a report, or reviewing a PR.

• Discover: The agent gathers what it needs before acting. In Claude Code, this means reading files, checking git status, and running a test suite to see the current state.

• Plan: The agent decides its own steps. The quality of this plan determines how many iterations the loop needs.

• Execute: In Claude Code, this means tool calls, file writes, and bash commands. A well-built loop treats errors as inputs to the next iteration.

• Verify: The agent checks whether the goal was met. A weak verifier produces a loop that exits early, claiming success. A strong verifier produces a loop that finishes the job.

So, what makes a good loop?

Three Qualities of a Good Loop

Every loop that works in production has three things, and if you miss one, your loop is likely to fail.

# 1: A Clear Stop Condition

Without a stop condition, the loop runs until your API credits expire or you manually stop it.

A stop condition has two parts:

Success condition: the measurable state that means the job is done.

all tests passing
coverage above 80%
PR checks green
zero lint errors

Safety cap: a maximum turn count that stops the loop no matter the result.

stop after 10 tries
stop after 5 attempts
stop after 15 runs

The safety cap protects you from an agent that is stuck and burns through your Claude Code budget.

/goal all tests passing and coverage above 80%, stop after 10 tries

2: Context Management

After a dozen iterations, the agent’s context window fills with test logs, error messages, old file states, and intermediate reasoning.

To fix context pollution in Claude Code:

• Keep the latest error and the file in question. Everything else from previous iterations should be stripped

• Summarize old steps into a short note. Claude Code’s /compact command does this automatically. It compresses the conversation history into a brief summary and keeps only the essential context for the next iteration.

• Remind the agent of the goal on every cycle. Your CLAUDE.md file is the right place for this. Whatever you put in CLAUDE.md is included at the start of every session and every sub-agent context.

3: Error Recovery

When the agent runs a command and it fails, something in the loop must decide what to do next.

Without a plan, the agent stops at the first failure and waits for you. That defeats the purpose of the loop.

In Claude Code, error recovery is built in. When a bash command fails, Claude reads the error output and uses it to choose the next action.

You do not need to build this yourself, but you do need to know it exists so you can write prompts that expect errors.

The key insight: design your loop assuming commands will fail. Your stop condition should be based on the goal being met, not on commands running without errors.

Three Claude Code Loop Commands

Claude Code has three native loop commands. Each one handles a different trigger and use case.

1) /goal: The Outcome-Based Loop

/goal is what you use when you know what done looks like. You define the success condition and a safety cap, and Claude Code handles the rest.

/goal all tests passing and no type errors, stop after 10 tries

After you run this, Claude Code:

1. Runs the test suite

2. Reads the failures

3. Fixes the failing code

4. Runs tests again

5. Checks whether the goal condition is now true

6. If yes: exits with a success message

7. If no: loops again up to the turn cap

An evaluator model checks your goal condition after each iteration. This is a separate model call, not the one used in the session.

Writing a good /goal condition:

Strong conditions are measurable and binary:

/goal all 47 tests passing, stop after 8 tries
/goal coverage above 80% and no lint warnings, stop after 5 tries
/goal PR checks all green and no TODO comments in changed files, stop after 10 tries

Weak conditions produce loops that never exit:

/goal make the code better               ← not measurable
/goal fix the issues you find            ← not binary
/goal improve test coverage              ← no threshold

/goal all tests passing, stop after 5 tries

2) /loop: The Time-Based Loop

/loop is what you use when the work is recurring and reacts to external events rather than working toward a single goal

/loop 5m check the PR for new review comments and address them

This runs every 5 minutes; Claude checks the PR, reads any new comments since the last check, addresses them, and waits for the next interval.

The difference from /goal: /loop does not have a stop condition. It keeps running until you close the terminal. Use it for tasks that are ongoing

/loop 2m check for failing CI and fix the errors
/loop 10m read #project-feedback and triage new issues
/loop 30m check if any deploys failed and roll them back

/loop 2m check for any failing tests and fix them

3) /schedule: The Cloud-Based Loop

/schedule is /loop that keeps running after you close the laptop. It moves the loop to the cloud.

/schedule every morning: check #project-feedback for new bugs and triage them

The difference from /loop:

• /loop stops when you close the terminal

• /schedule keeps running on Anthropic’s infrastructure

Use /schedule for daily digests, nightly CI runs, and any task that needs to happen on a fixed schedule whether you are at your desk or not.

4) Proactive loop: combining /schedule and /goal

The most powerful pattern in Claude Code is combining both commands:

/schedule every hour: check #project-feedback for bug reports
/goal do not stop until every report found this run is triaged, 
actioned, and responded to

This creates a fully autonomous loop:

• The schedule triggers every hour

• The goal runs until every bug report in that batch is handled

/schedule every morning: check the PR queue and generate a daily digest of what needs review

Real Loop in Claude Code: PR Readiness Loop

Here is the complete loop engineering example using Claude Code on a real example.

Suppose this is the case:

You have a branch ready to merge, but the CI is failing because three tests are broken, coverage has dropped below 80%, and there are two lint errors.

Normally, you would fix these manually, turn by turn. Loop engineering lets the agent handle the entire cycle.

Step 1: Design the Loop

Before you start designing the loop, you need to answer these four questions:

1. What does done look like? All tests passing, coverage above 80%, zero lint errors.

2. What is the safety cap? 10 iterations maximum. After that, something structural is wrong, and you need to look.

3. What context management does the agent need? The CLAUDE.md in this project already documents the test command and the coverage threshold. The agent will not drift if it keeps re-reading CLAUDE.md at the start of each iteration.

4. What errors should the agent recover from vs stop on? Recover from: test failures, lint errors, coverage gaps. These are the job. Stop on: syntax errors that prevent the test suite from running at all. That requires human eyes.

Step 2: Run the Loop

/goal all tests passing, coverage above 80%, no lint errors, stop after 10 tries

Iteration 1:
- Runs: pytest --cov=app tests/
- Reads: 3 failures, coverage 71%, 2 lint errors
- Plans: fix the three failing tests first
- Writes: updated test fixtures
- Re-runs: pytest
- Evaluates: still failing, loops again

Iteration 2:
- Runs: pytest
- Reads: 1 failure remaining, coverage 74%
- Plans: fix the remaining test
- Writes: fixes the edge case in auth validation
- Re-runs: pytest
- Evaluates: all passing now, checks coverage

Iteration 3:
- Runs: pytest --cov=app
- Reads: all passing, coverage 76%, 2 lint warnings still
- Plans: fix lint errors
- Writes: reformats two functions
- Re-runs: pylint
- Evaluates: zero warnings, coverage 77%, not above 80% yet

Iteration 4:
- Adds missing test cases to reach 80%
- Re-runs full suite
- Evaluates: all conditions met
- EXITS: goal reached in 4 iterations

Step 3: Find the Loop Limitations

The PR readiness loop works because one agent does one thing (fix the PR), but it cannot :

• Review its own fixes independently—The agent that wrote the test fix is the same agent that evaluates whether the fix is correct. It cannot be a credible skeptic of its own work.

• Parallelize— If there are five categories of issues (tests, coverage, lint, types, security), the loop handles them one category at a time. They cannot run simultaneously.

• Visualize the flow— If you read the transcript, you see 47 tool calls in sequence. You cannot quickly tell which iteration caught the coverage gap or which fix introduced a new issue.

These three limitations can be fixed by one solution that we will build next.

Resources

For this issue, these are the resources available:

• Testing Repo

• Tested Loop Templates Prompt (Members Resource Library)

Other: Coming Up Issues

The next issues in this Masterclass Series will cover:

• Claude Code Subagents Masterclass — Building your AI team

• Claude Code MCP Masterclass — Extending Claude’s capabilities

How are You Using Loops in Claude Code?

Let me know your thoughts, tips, and any questions in the comments below.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Hello, thank you for being part of our Claude Code Masterclass community. We are still growing past 79k members, and I am grateful for every one of you.

This is Issue #5 of the Last Week In Claude Code series.

The last week had a lot going on:

• Agents can now message each other across machines

• MCP shipped its biggest update since launch

• Claude Code can now run on your own servers

• I tested DeepSeek V4-Flash against Fable 5 with some surprising results

We are also adding a new section starting this week: External Models Testing & Tools, where I share what I am testing outside of Anthropic models and what is worth your time.

What Happened Last Week In Claude Code?

#1) Cross-Session SendMessage — Agents Can Now Talk to Each Other

Version: 2.1.224

Claude Code sessions can now send messages to each other across tabs, machines, and projects

What It Does

Before this, agents were isolated. You could run parallel sessions, but no way for sessions to coordinate without your input

Now one session can message another directly using SendMessage and use ListAgents to discover all available sessions across your machines.

# List all available sessions (including other machines)
ListAgents

# Sessions appear as:
# name [ref] — local or remote

SendMessage can also start a new conversation with a Remote Control session on another machine by name.

Auto mode now evaluates messages sent between agents via SendMessage before dispatch, so one compromised agent cannot instruct another to bypass permissions.

Multi-agent workflows just got coordination. A parent agent can now delegate to a specialist agent, check its progress, and act on the result.

I shared the complete test results in my Medium tutorial; learn more here

#2) Auto Mode — Now the Default for Everyone

Version: 2.1.207+

Auto mode is now the default permission mode across all Claude Code sessions.

What Changed

Previously, you had to opt in or configure auto mode manually using the shift+tab.

Now, it is on by default for all users.

Auto mode classifies every tool call before it runs, deciding automatically whether it is safe to allow or needs your approval. The goal is fewer interruptions on routine work.

What You Can Still Control

Auto mode does not mean Claude does everything without asking. It means the classifier makes the call instead of defaulting to a prompt.

You can still:

# Switch to manual at any time
/config → Permission mode → Manual

# Or via settings
{ "defaultMode": "manual" }

# Disable auto mode entirely
{ "disableAutoMode": true }

Recent improvements to auto mode worth knowing:

• Parallel tool call checks are now cache-efficient; faster decisions when multiple tools run at once

• Safety filter refusals no longer count toward the consecutive-block limit; Claude moves on instead of retrying

• SendMessage between agents now goes through the classifier before delivery

I shared a quick tutorial on Medium to help you learn how Auto mode works.

#3) Anthropic MCP Stateless — The Biggest MCP Update Since Launch

Spec: MCP 2026-07-28

The Model Context Protocol just shipped its most significant update since it launched.

MCP is now stateless.

What Changed?

The old MCP used a bidirectional stateful protocol; every connection needed a persistent session, a handshake, and a session ID. Servers had to maintain state between calls.

MCP is now a request/response model like HTTP:

• MCP servers can now run on serverless and edge infrastructure (Cloudflare Workers, AWS Lambda)

• No more session management to work around

• Easier to scale, easier to deploy, easier to build

MCP recently surpassed 400 million monthly SDK downloads. There are now over 950 MCP servers in the Claude connector directory.

What is Deprecated?

The old spec is not going away immediately, but they gave a 12-month deprecation window, so you should start planning:

• Roots, Sampling, Logging, and SSE are deprecated

• The initialize/initialized handshake is removed

• The Mcp-Session-Id header is removed

I created a complete Stateless MCP demo that you can follow to see how to carry out the updates or build your new MCP using the stateless protocol

For Claude Code Users

If you use MCP servers in your workflows, check whether your servers have been updated to the new spec.

Many MCP servers will need a refactor; check out my full walkthrough on Medium: Anthropic Just Overhauled MCP (I Built My First Stateless MCP Server)

#4) Self-Hosted Runner — Run Claude Code on Your Own Machines

Version: 2.1.224

You can now turn your own machines or containers into a place where Claude Code sessions run.

Available on Team and Enterprise plans.

What It Does

claude self-hosted-runner

This registers your machine as a runner. Claude Code web, mobile, and desktop sessions can then execute on it instead of Anthropic’s cloud infrastructure.

For teams with compliance requirements, air-gapped environments, or sensitive codebases, running Claude Code on your own infrastructure changes what is possible.

What to Know

• Available on Team and Enterprise plans only

• If the --base-dir cannot be created or written, it exits at startup with a clear error instead of registering and failing every session

• Archive plugin installs (zip over HTTPS) are also supported in this version; useful for air-gapped setups

# Register your machine as a runner
claude self-hosted-runner

# With a custom base directory
claude self-hosted-runner --base-dir /path/to/dir

I have not yet tested the self-hosted runner since I don’t have a team or max plan; in the future, I will demonstrate how this works.

#5) Quick Wins — Subagent Cap Removed & Plugins Activate Immediately

Two smaller changes that improve Claude Code daily workflows.

Subagent Cap Removed

The 200-subagent-per-session spawn limit is gone. Long-running sessions no longer refuse to spawn new agents after hitting the cap.

Plugins Activate Immediately

Installing a plugin no longer requires /reload-plugins to take effect.

# Before: install, then reload
/plugin install my-plugin
/reload-plugins

# Now: install and it is live
/plugin install my-plugin

External Models Testing & Tools

A new section where I share what I am testing outside of Anthropic models and what is worth your time.

DeepSeek V4-Flash on Claude Code — 71x Cheaper Than Fable 5

DeepSeek just released the V4-Flash API into public beta, and I ran it on Claude Code.

The benchmark: Terminal-Bench 2.1, the evaluation for agentic coding — DeepSeek V4-Flash scores 82.7. That beats Fable 5 on this benchmark.

71x cheaper on input. 178x cheaper on output.

My real session cost: Built a full Windows screen time monitor app; background tracker, dashboard with three tabs, alerts, SQLite storage. Total cost: $0.13.

Two ways to run it:

Via Ollama:

ollama launch claude --model deepseek-v4-flash

Via Direct API:

export ANTHROPIC_BASE_URL="https://api.deepseek.com/v1"
export ANTHROPIC_API_KEY="your-deepseek-api-key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-flash"
claude

The direct API gives you lower latency and the full 1M context window.

You can see my full test of DeepSeek v4 Flash on Claude Code here — I Tried DeepSeek V4-Flash on Claude Code (It Beats Fable 5 at 71x Lower Cost)

Finally, I built and open-sourced a framework for structured AI coding that works across Claude Code, Codex, Cursor, and OpenCode. We will feature it in next week's issue.

You are now up to date with the latest major Claude Code updates.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

First, welcome to all new subscribers. We have finally reached more than 79,000 members. I’m very grateful for every one of you and am still overwhelmed by the support and pledges you have sent — Thank you once again.

This issue brings you the #3 issue in the Claude Code Masterclass Series — Claude Code Hooks Masterclass

CLAUDE.md only defines rules but doesn’t enforce them.

You can tell Claude, “always run tests before committing” in your CLAUDE.md. Claude will read it, acknowledge it, and then... ask you if you want to run test again and again.

To enforce these rules, we need to run automatic actions that fire at specific points or events.

That’s why Claude Code introduced hooks.

Hooks are not as complicated as many new users think; they are simple to use once you understand the basics.

They are automated actions that trigger at specific points in Claude’s workflow:

• Hooks run without asking

• Hooks can allow, deny, or modify what happens next

• Hook examples: When a file changes, a command executes, or a session starts

In this issue, you will learn the fundamentals of why we need hooks, show you the hooks events, basic hooks examples, and advanced hooks patterns in real projects.

I will take you from understanding basics to implementing production-ready automation.

You’ll master:

• What hooks are and when they trigger

• Hook types

• How to configure hooks in .claude/settings.json

• Exit codes and decision control

• Production-ready hook patterns you can use

• How hooks and CLAUDE.md work together

Let’s start with understanding the basics.

What Are Hooks?

Hooks are event listeners for Claude Code’s workflow.

When Claude performs an action such as running a command, modifying a file, or starting a session, it fires events. Hooks listen for these events and execute automated responses.

Hooks are like middleware in a web framework, where a request comes in, middleware intercepts it, decides whether to allow it, modify it, or block it entirely.

In summary :

For our practical example, we will use a reference project: an AI PDF Chat — SaaS, where users upload PDFs and chat with the docs.

I will demonstrate each hook concept with AI PDF Chat project scenarios that mirror what you’d encounter in production.

Here’s the project structure:

pdfchat/
├── .claude/
│   ├── settings.json          # Where project hooks live
│   └── hooks/                 # Custom hook scripts
├── CLAUDE.md
├── backend/
│   ├── api/
│   │   ├── auth.py
│   │   ├── documents.py       # PDF upload endpoints
│   │   └── chat.py            # Chat endpoints
│   ├── services/
│   │   ├── pdf_parser.py      # Extract text from PDFs
│   │   ├── embeddings.py      # Chunk and embed content
│   │   └── chat_engine.py     # RAG + LLM responses
│   └── models/
├── frontend/
│   └── src/
├── tests/
└── requirements.txt

Imagine you’ve written a perfect CLAUDE.md for this AI PDF Chat project that includes these rules:

• Always run tests after changing API endpoints

• Never commit without formatting Python files

• Check the database connection before starting work

• Block direct edits to migration files

But there is a problem:

Claude reads these rules and understands them, but still asks:

I've updated the chat endpoint. Would you like me to run the tests now?

Without hooks:

With hooks:

With hooks, we achieved zero manual intervention, reduced the steps, improved efficiency, and made the process faster.

Event-Driven Automation

Hooks operate on a trigger-and-response model. Each hook type responds to a specific event in Claude’s lifecycle.

Claude Code Hooks Lifecycle

These are the events Claude fires:

But, you don’t need all hooks, for most projects 3-5 strategically placed hooks is all you need!

For AI PDFChat, we might use:

• SessionStart - Check connections before work starts

• PreToolUse - Block dangerous operations on production config

• PostToolUse - Auto-format and test after code changes

• Notification - Desktop alert when Claude is waiting on you

The next question is, how do these hooks fire?

Hooks Execution

Hooks run as shell commands.

When an event fires, Claude:

1. Checks your settings files for matching hooks

2. Executes the hook command (or multiple commands in parallel)

3. Reads the exit code and any JSON the hook printed

4. Decides what to do next based on the result

You can see your existing hooks inside the .claude/settings.json

Here’s a simple PostToolUse hook that formats Python files:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(backend/**/*.py)",
            "command": "bash .claude/hooks/format_python.sh"
          }
        ]
      }
    ]
  }
}

And the script, which reads the path from stdin:

#!/bin/bash
# .claude/hooks/format_python.sh
FILE=$(jq -r '.tool_input.file_path')
[[ "$FILE" == *.py ]] && black "$FILE"
exit 0

Execution Steps:

• Claude edits a Python file in backend/

• The Edit tool triggers

• The matcher matches the tool name, and if narrows it to the path

• The hook script runs black

• File gets formatted

• Claude continues without asking

Hooks also have types based on how they work, and it’s important to differentiate.

Command Hooks vs Prompt Hooks

The two hook handler types you'll use most are command hooks and prompt hooks.

Command hooks execute bash commands:

{
  "type": "command",
  "command": "bash .claude/hooks/format_python.sh"
}

Prompt hooks use Claude’s LLM to evaluate (advanced):

{
  "type": "prompt",
  "prompt": "Does this change affect user authentication? Respond with YES or NO."
}

Prompt hooks are powerful but slower and cost more tokens. Most production hooks use commands.

For our AI PDF Chat project, we’ll stick with command hooks because they’re fast and deterministic.

Now that you understand hooks fire at specific triggers, the next question is: what is the process that a hook goes through before it stops —from start to finish?

This is what we refer to as a hook lifecycle.

Here’s what happens when you ask Claude to modify backend/api/chat.py:

Multiple hooks can fire during a single interaction, and run in parallel when multiple hooks match the same event.

Complete Hook Lifecycle (Practical Examples)

Claude Code provides a variety of hooks.

Each one fires at a different point in the workflow. Understanding when each hook triggers is the key to effective automation.

Let’s walk through all the hook types in chronological order, following our project development session.

1. Setup Hook

When it fires: The very first time Claude Code runs in a project directory.

Runs: Once per project.

Use case: Initialize project dependencies, create config files, and set up databases.

For our project, set up handles for first-time initialization:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/session_start.sh"
          }
        ]
      }
    ]
  }
}

The setup script:

#!/bin/bash
# .claude/hooks/setup.sh

# Create .env from template
if [ ! -f .env ]; then
  cp .env.example .env
  echo "Created .env file"
fi

# Install Python dependencies
pip install -r requirements.txt

# Initialize database
python -m alembic upgrade head # Runs alembic upgrade head which could apply migrations to the wrong database without meaning to

# Create uploads directory
mkdir -p storage/uploads

echo "PDFChat setup complete"

When you’d see this: The first time you run Claude Code in a freshly cloned repo.

Here’s what happens:

1. The SessionStart hook fires when Claude Code opens the project

2. The hook runs .claude/hooks/setup.sh

3. The script checks if .env exists — if not, it copies from .env.example

4. It also creates the storage/uploads directory for PDF uploads

When I ran Claude Code for the first time in this project, the hook fired and created the .env file using the template I provided in the project root.

2. SessionStart Hook

When it fires: Every time you start a new Claude Code session.

Runs: Once per session.

Use case: Verify connections, check environment, validate prerequisites.

Whatever a SessionStart hook prints to stdout is added to Claude's context before your first message. That makes it the right place to inject live state: current branch, uncommitted files, which services are up.

For our project, SessionStart checks that critical services are available:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/session_start.py"
          }
        ]
      }
    ]
  }
}

The session start script example for production:

#!/usr/bin/env python3
# .claude/hooks/session_start.py

import sys
import os
from sqlalchemy import create_engine
from pinecone import Pinecone

def check_database():
    """Verify PostgreSQL connection"""
    try:
        engine = create_engine(os.getenv('DATABASE_URL'))
        engine.connect()
        return True
    except Exception as e:
        print(f"Database connection failed: {e}")
        return False

def check_vector_db():
    """Verify Pinecone connection"""
    try:
        pc = Pinecone(api_key=os.getenv('PINECONE_API_KEY'))
        pc.list_indexes()
        return True
    except Exception as e:
        print(f"Pinecone connection failed: {e}")
        return False

def check_openai_key():
    """Verify OpenAI API key exists"""
    if not os.getenv('OPENAI_API_KEY'):
        print("OPENAI_API_KEY not set")
        return False
    return True

if __name__ == "__main__":
    checks = [
        check_database(),
        check_vector_db(),
        check_openai_key()
    ]
    
    if all(checks):
        print("All systems ready")
        sys.exit(0)
    else:
        print("Some services unavailable")
        sys.exit(0)  

For my test, I will run a simple script to check the environment on session start :

The script verifies that:

• The .env file exists

• Required API keys are configured

• It logs the session start time for debugging

When you’d see this: Every time you open Claude Code. It runs before Claude processes your first message.

Note: SessionStart hooks should be fast, and network checks add startup latency

3. UserPromptSubmit Hook

When it fires: Every time you send a message to Claude.

Runs: Before Claude processes your request.

Use case: Logging, context tracking, request validation.

For our project, we might log all requests for debugging:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/log_prompt.sh"
          }
        ]
      }
    ]
  }
}

For my test, I'll log every message I send to Claude.

#!/bin/bash
# .claude/hooks/log_prompt.sh
PROMPT=$(jq -r '.prompt')
echo "[$(date)] User: $PROMPT" >> .claude/conversation.log
exit 0

This hook fires before Claude processes the request — useful for debugging or tracking conversation flow.

Quick Notes:

• UserPromptSubmit hooks time out after 30 seconds. This hook blocks your prompt until it finishes, so keep it fast.

• Anything a UserPromptSubmit hook prints to stdout is added to Claude's context alongside your message. Redirect to a file if you only want a log.

Most projects don’t need this hook, but it’s invaluable when debugging complex workflows or tracking how long tasks take between prompts.

4. PreToolUse Hook

When it fires: Before Claude executes any tool (bash, edit, write, etc).

Runs: Every time a tool is about to execute.

Use case: Block dangerous operations, validate inputs, and enforce policies.

For our project, PreToolUse prevents accidental edits to database migrations:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block_migrations.sh"
          }
        ]
      }
    ]
  }
}

The blocking script:

#!/bin/bash
# .claude/hooks/block_migrations.sh
FILE=$(jq -r '.tool_input.file_path')

if [[ "$FILE" == *migrations/* ]]; then
  echo "Direct migration edits are blocked." >&2
  echo "Use: alembic revision --autogenerate -m 'description'" >&2
  exit 2
fi

exit 0

For my test, I'll block direct edits to migration files. The hook checks if the file path contains "migrations" and blocks the edit with exit code 2.

When I asked Claude to edit migrations/001_init.py —the hook intercepted the request and blocked it.

Claude understood the restriction and suggested the correct workflow, using Alembic to generate migrations properly.

Claude tries to edit a migration file. Hook fires and Exit code 2 blocks it. Claude sees the error and suggests the correct approach. You would see this when you ask Claude to “fix that migration file,” and it tries to edit it directly.

5. PostToolUse Hook

When it fires: After Claude successfully executes a tool.

Runs: Every time a tool completes.

Use case: Auto-formatting, running tests, validation, and cleanup.

For our project, PostToolUse auto-formats Python files after any edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/format_python.sh" }
        ]
      }
    ]
  }
}

Script:

INPUT=$(cat)
FILE=$(echo "$INPUT" | grep -o '"file_path":"[^"]*"' | cut -d'"' -f4)
if [[ "$FILE" == *.py ]]; then
  black "$FILE" 2>/dev/null
  echo "[$(date)] Formatted: $FILE" >> .claude/format.log
fi

For my test, I'll auto-format Python files after every edit. The hook runs black on any Python file Claude creates or modifies.

I asked Claude to create a poorly formatted function: def hello( x,y, z ): return x+y+z

The moment the file was written, the hook ran black and reformatted it : indentation, spacing, PEP 8 compliant. You would see this every time Claude edits a Python file in backend/.

6. Notification Hook

When it fires: When Claude wants to notify you of something.

Runs: On informational events (not blocking).

Use case: Send alerts to Slack, log important events, or trigger webhooks.

For PDFChat, we might alert when tests fail:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/notify_slack.sh" }
        ]
      }
    ]
  }
}

For my test, I tested logging every notification Claude Code sends.

Notifications fire when Claude needs permission, goes idle, or completes authentication.

You would use it for integrations like Slack alerts or desktop notifications when Claude is waiting for you.

7. PermissionRequest Hook

When it fires: When Claude needs explicit permission for an operation.

Runs: On sensitive operations that require approval.

Use case: Add additional validation before destructive actions.

A good example for our project: we require confirmation before deleting user documents:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/guard_uploads.sh" }
        ]
      }
    ]
  }
}

When Claude tries to delete a PDF from user storage, you will see this hook in action.

For my test, I'll log every time Claude asks for permission. This fires when Claude needs approval for sensitive operations, such as running commands or deleting files.

I created a permission logger script, then asked Claude to do something requiring permission: run ls -la

You can use it to auto-approve certain operations, add extra validation before destructive actions, or log all permission requests for audit trails.

#!/bin/bash
# Auto-approve read-only git commands
CMD=$(jq -r '.tool_input.command')

if [[ "$CMD" =~ ^git\ (status|log|diff|branch) ]]; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PermissionRequest",
      decision: { behavior: "allow" }
    }
  }'
fi

exit 0

8. Stop Hook

When it fires: When Claude completes a task.

Runs: At the end of Claude’s response.

Use case: Generate summaries, update logs, clean up temp files.

For our project, we might summarize what changed:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/stop_logger.sh" }
        ]
      }
    ]
  }
}

For my test, I'll log every time Claude completes a task.

The Stop hook fires when Claude finishes responding; useful for summaries, cleanup, or triggering follow-up actions.

This would be useful after Claude finishes implementing a feature. You could extend this to generate git diffs, run a final test suite, or send a "task complete" notification to Slack.

Careful with Stop hooks. Exit 2 stops Claude from stopping and continues the turn. Check stop_hook_active in the hook input before returning a blocking exit, or you'll loop:

ACTIVE=$(jq -r '.stop_hook_active')
[[ "$ACTIVE" == "true" ]] && exit 0

9. SubagentStop Hook

When it fires: When a subagent (parallel task) completes.

Runs: After delegated tasks finish.

Use case: Aggregate results, merge outputs, and clean up subagent artifacts.

When Claude delegates a codebase exploration to a subagent, SubagentStop lets you capture what it found before that context is discarded.

{
  "hooks": {
    "SubagentStop": [
      {
        "matcher": "Explore",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/subagent_stop.sh" }
        ]
      }
    ]
  }
}

For my test, I log the time when the subagent completes a task :

You would use this when Claude processes multiple PDFs in parallel and needs to combine results.

10. SubagentStart Hook

There's a matching SubagentStart event that fires when a subagent spawns

11. SessionEnd Hook

When it fires: When a session terminates: closing Claude Code, /clear, or logout

Runs: Once, at session termination.

Use case: Final cleanup, save logs, backup state.

For PDFChat, save the session transcript:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/session_end.sh" }
        ]
      }
    ]
  }
}

Script Example :

#!/bin/bash
# .claude/hooks/session_end.sh
TRANSCRIPT=$(jq -r '.transcript_path')
mkdir -p .claude/backups
cp "$TRANSCRIPT" ".claude/backups/session_$(date +%s).jsonl"
exit 0

For my test, I'll log when I close Claude Code. The SessionEnd hook fires once when the session terminates — perfect for cleanup and final logging.

When I /exit or close Claude Code, this hook runs. You can use it to backup the session transcript, save final state, or log total session time.

But as I mentioned earlier, you do not need all these hooks in one project. For our project, the most useful hooks are:

1. SessionStart - Verify services are ready

2. PreToolUse - Block dangerous operations

3. PostToolUse - Auto-format and test

4. UserPromptSubmit - Inject live context into every prompt

5. Stop - Summarize changes

The others exist for specialized use cases. For your start, I recommend these five.

The next step: when you need to run more than one hook at a time, you apply parallel execution.

Parallel Execution

This is useful when multiple hooks match the same event; they all run in parallel. For our project, I can run these two hooks in parallel :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/format_python.sh" },
          { "type": "command", "command": "bash .claude/hooks/lint_python.sh" }
        ]
      }
    ]
  }
}

Both hooks fire simultaneously after editing a Python file.

Next, let’s look at the hooks configuration syntax and how to write these hooks in .claude/settings.json.

Identical handlers are automatically deduplicated: command hooks by command string; HTTP hooks by URL. If two settings files register the same hook, the hook runs only once.

Hook Configuration Anatomy

Hooks come from six places:

• ~/.claude/settings.json — All your projects

• .claude/settings.json — This project, committed

• .claude/settings.local.json —This project, gitignored

• Managed policy settings —Organization-wide

• Plugin hooks/hooks.json —While the plugin is enabled

• Skill or agent frontmatter — While that component is active

The best example of hooks is those that in .claude/settings.json.

This file is located in your project root and defines every hook Claude Code will execute; this is the best place to begin learning how to write your custom hooks.

Let’s break down the configuration syntax so you can write your own hooks confidently.

To master the hooks syntax, you need to understand these six things :

• Basic structure

• Matcher object

• Matcher Fields

• Path Patterns

• Environmental variables

• Timeout configuration

Let’s cover each with an example:

1. Basic Structure

Here’s what .claude/settings.json looks like for our project:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/session_start.sh"
          }
        ]
      }
    ]
  }
}

Every hook configuration has three levels:

• The event name — the key under hooks, like PreToolUse or Stop

• A matcher group — filters when it fires

• One or more handlers — each with a type (command, http, mcp_tool, prompt, agent) and what to run

2. Matcher Object

Matchers filter when hooks execute. Without a matcher, the hook fires on every instance of that event type. With a matcher, it only fires when conditions match.

For our project, we only want to format Python files when they're edited or written:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/format_python.sh"
          }
        ]
      }
    ]
  }
}

The hook fires only when:

• Tool is Edit or Write (not Bash, Read, etc.)

Note: To filter by file path, your script reads the JSON input from stdin and checks the path itself; there's no pathPattern field in the matcher.

3. Matcher Fields

Different hook types support different matchers :

For PreToolUse and PostToolUse:

{
  "matcher": "Edit|Write"
}

Matches tool names: Edit, Write, Bash, Read, Glob, Grep, Task, NotebookEdit, WebFetch, WebSearch

For Notification:

{
  "matcher": "permission_prompt"
}

Matches notification types: permission_prompt, idle_prompt, auth_success, elicitation_dialog,elicitation_complete, elicitation_response, agent_needs_input, agent_completed

For SessionStart:

{
  "matcher": "startup|resume"
}

Matches how the session started: startup, resume, clear, compact and fork (a session forked from another).

For SessionEnd:

{
  "matcher": "clear|logout"
}

Matches why the session ended: clear, resume, logout, prompt_input_exit, bypass_permissions_disabled and other.

How a Matcher is Evaluated

How the matcher is read depends on what's in it:

• *, "", or omitted: Matches everything

• Letters, digits, _, -, spaces, ,, | : Exact string, or a list — Edit|Write matches either

• Anything else : A regular expression, unanchored

Two things to watch:

• Edit.* also matches NotebookEdit, so anchor it as ^Edit$ if you mean only Edit.

• And matching every tool from an MCP server needs the .* — mcp__memory matches nothing, mcp__memory__.* matches all of them

Some event ignore matchers:

• UserPromptSubmit, Stop, PostToolBatch, MessageDisplay, CwdChanged, TaskCreated, TaskCompleted, WorktreeCreate and WorktreeRemove don't support matchers.

4. Path Patterns (Globs)

Path patterns use glob syntax to match files.

However, path filtering happens inside your script, not in the matcher field. The matcher only filters by tool name.

Here are the patterns you’ll use most with examples:

For our project, filtering by path in the script:

#!/bin/bash
# .claude/hooks/format_by_path.sh

INPUT=$(cat)
FILE=$(echo "$INPUT" | grep -o '"file_path":"[^"]*"' | cut -d'"' -f4)

# Match backend/**/*.py
if [[ "$FILE" == *"backend/"* && "$FILE" == *.py ]]; then
  black "$FILE"
fi

# Match migrations/**/*.py - block with exit 2
if [[ "$FILE" == *"migrations/"* && "$FILE" == *.py ]]; then
  echo "Use alembic instead" >&2
  exit 2
fi

# Match frontend/**/*.js or frontend/**/*.jsx
if [[ "$FILE" == *"frontend/"* && ("$FILE" == *.js || "$FILE" == *.jsx) ]]; then
  prettier --write "$FILE"
fi

exit 0

5. Environment Variables

Hooks have access to special environment variables:

For our project, SessionStart hook:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd ${CLAUDE_PROJECT_DIR} && python .claude/hooks/session_start.py"
          }
        ]
      }
    ]
  }
}

For PostToolUse hooks, the file path arrives on stdin. Read it in your script:

#!/bin/bash
# .claude/hooks/format_python.sh
FILE=$(jq -r '.tool_input.file_path')
black "$FILE" && pylint "$FILE"
exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/format_python.sh"
          }
        ]
      }
    ]
  }
}

So far, we’ve only used command-type hooks, which execute bash commands.

As I mentioned earlier, there are also prompt-type hooks . Here is a simple example:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "prompt",
            "if": "Edit(backend/models/**/*.py)",
            "prompt": "Does this change alter the database schema? If yes, block it and tell the user to generate a migration instead."
          }
        ]
      }
    ]
  }
}

1. Hook fires

2. Claude analyzes the change using the prompt

3. Claude responds YES or NO

4. Appropriate commands run based on the response

6. Timeout Configuration

By default, hooks timeout after 600 seconds. For most projects that's long — but for slow operations you may want to cap it sooner or raise it :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "pytest tests/",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

This caps the test suite at 5 minutes.

We can implement this in our project’s embedding tests (which can be slow):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(backend/services/embeddings.py)",
            "command": "pytest tests/test_embeddings.py -v",
            "timeout": 180
          }
        ]
      }
    ]
  }
}

Decision Control

Hooks don’t just run commands. They make decisions that control what Claude does next.

Every hook returns an exit code. That exit code tells Claude whether to proceed, block, or handle the situation differently.

Exit Codes: The Control Mechanism

When a hook finishes executing, it returns an exit code. Only 0 and 2 are special: any other value is a non-blocking error.

Claude reads this code and acts accordingly.

For PDFChat, this is how we enforce it.

Exit Code 0: Allow

Exit code 0 means “everything is fine, proceed.”

For a SessionStart hook that checks database connectivity:

#!/bin/bash
# .claude/hooks/session_start.sh

# Check if PostgreSQL is running
pg_isready -h localhost -p 5432

if [ $? -eq 0 ]; then
  echo "Database connected"
  exit 0  # Allow session to continue
else
  echo "Database not running"
  exit 0  # Still allow (just warn)
fi

What happens: Hook runs, prints status, session continues regardless. Useful for informational checks.

Exit Code 2: Deny

Exit code 2 means “block this operation.”

For PDFChat, we never want Claude editing migration files directly:

#!/bin/bash
# .claude/hooks/block_migrations.sh

echo "Direct migration edits are blocked." >&2
echo "Use: alembic revision --autogenerate -m 'description'" >&2
exit 2

Hook configuration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "bash .claude/hooks/protect_uploads.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
CMD=$(jq -r '.tool_input.command')
if [[ "$CMD" == *storage/uploads* ]]; then
  echo "Cannot delete user uploads directly." >&2
  echo "Use: python scripts/cleanup_uploads.py --safe" >&2
  exit 2
fi
exit 0

What happens: Claude tries to edit a migration file. Hook fires. Exit code 2 blocks it. Claude sees the error message and suggests an alternative.

Conditional Logic in Hooks

Use exit codes to implement smart decisions.

For PDFChat, only run tests if the change affects API logic:

#!/bin/bash
FILE=$(jq -r '.tool_input.file_path')

if [[ "$FILE" == *backend/api/* || "$FILE" == *backend/services/* ]]; then
  pytest tests/ -v || {
    echo "Tests failed after editing $FILE" >&2
    exit 2
  }
fi
exit 0

What happens: Edit a config file? No tests. Edit the chat API? Tests run. Hook decides dynamically.

Chaining Decisions

Use && and || for sequential logic. If any step fails, the chain stops.

For PDFChat, ensure formatting succeeds before testing:

#!/bin/bash
# .claude/hooks/format_and_test.sh
FILE=$(jq -r '.tool_input.file_path')

black "$FILE" && pytest tests/api/ -v || {
  echo "Pipeline failed on $FILE" >&2
  exit 2
}

exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(backend/api/**/*.py)",
            "command": "bash .claude/hooks/format_and_test.sh"
          }
        ]
      }
    ]
  }
}

What happens: Black formats the file. If formatting fails, pytest never runs. The error goes to Claude via stderr so it knows what to fix.

JSON Responses (Advanced)

Some hooks can return JSON for richer control: allowing, denying, escalating to you, or rewriting a tool’s arguments. This is the way to go beyond a simple block.

The rule is simple: always exit 0 when returning JSON. The JSON carries the decision, not the exit code.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(backend/models/**/*.py)",
            "command": "python .claude/hooks/validate_change.py"
          }
        ]
      }
    ]
  }
}

Example script:

#!/usr/bin/env python3
import json
import sys

is_safe = validate_operation()

if is_safe:
    sys.exit(0)  # No decision needed — normal permission flow continues

# Deny and tell Claude why
print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
        "permissionDecisionReason": "This change affects the database schema. Generate a migration with: alembic revision --autogenerate -m 'description'"
    }
}))

sys.exit(0)  # Exit 0 — the JSON carries the deny decision

permissionDecision accepts four values: allow, deny, ask (escalate to you), and defer (pass to the next hook).

Claude reads the reason and knows what to do instead.

Key Takeaways

Exit codes are how hooks enforce decisions:

• 0 = Success — no decision, unless your JSON says otherwise

• 2 = Block — stderr is sent back to Claude

• Anything else — a non-blocking error. The action still happens

For PDFChat:

• Use exit 2 to protect migrations, uploads, production files

• Use exit 0 for informational hooks (logging, notifications)

• Put your error message on stderr; that’s the only channel Claude reads

Next, we’ll look at production-ready hook patterns you can copy directly into PDFChat.

Production Hook Patterns

The PDFChat examples in this issue are a starting point.

In production, hooks are the automation layer that runs your entire engineering workflow: formatting, testing, protecting, alerting, and much more.

Any rule your team currently enforces through code review, documentation, or habit can become a hook.

1. Enforce Team Standards

If your team has a rule in a doc or gets caught in PR review, it belongs in a hook.

• A fintech team runs security linting on every file that touches payment logic

• A data team enforces schema validation before any model file is saved

• An agency enforces client-specific coding conventions per project

Hook type: PostToolUse: runs after every edit, before Claude moves on

2. Protect Sensitive Files

Some files and operations should never happen. Production configs, database migrations, generated code, deployment scripts.

• Block direct edits to migration files and tell Claude to use the migration tool instead

• Prevent any write to .env.production outside a deployment pipeline

• Stop rm -rf commands that target anything outside a temp directory

Hook type: PreToolUse: intercepts before the action happens

3. Gate Expensive Operations

When an action costs money or triggers external services, a hook can check conditions before it runs.

• Check today’s OpenAI token spend before running a large embedding job

• Verify the staging environment is healthy before running an integration test suite

• Block API calls to third-party services when a rate limit is approaching

Hook type: PreToolUse with exit 2: blocks and gives Claude a reason

4. Inject Live Context

Claude starts every session already knowing things it can’t see in your codebase.

• Which services are up or down

• What’s been deployed since the last session

• Current branch, open PRs, failing CI jobs

• Outstanding tickets assigned to you

Hook type: SessionStart: runs once, shapes the whole session

5. Close the Feedback Loop

Claude edits a file and doesn’t know if the tests passed, the build broke, or the linter found issues. PostToolUse can fix this behaviour:

• Run the affected test file after every code change

• Check the build after modifying a config

• Validate an API response schema after editing an endpoint

Hook type: PostToolUse — turns Claude from a one-shot editor into one that sees consequences

As I mentioned in the previous Claude.MD issue, hooks and CLAUDE.md work together to build on the Claude Code complete automation system.

Hooks + CLAUDE.md

CLAUDE.md defines the rules, and hooks enforce them.

Together, they create a self-documenting, self-enforcing development environment. Claude knows what to do and can’t deviate from it.

In the last Masterclass issue, we covered CLAUDE.md; the file that gives Claude persistent memory of your project and defines how it should behave.

CLAUDE.md only tells Claude what to do; it doesn’t make sure it happens.

Hooks are the enforcement layer. Since their introduction, they have become the core step towards building a complete Claude Code automated system.

Final Thoughts

Hooks are the feature that takes you from Level 2 to Level 3 on the mastery scale from Issue #1.

You now have the thing that puts you ahead of 90% of Claude Code users: automation that runs without asking.

Key takeaways:

• Hooks are event listeners; they fire at specific points in Claude’s workflow, not on a schedule

• Exit 2 blocks. Exit 1 does not, even though it’s the conventional Unix failure code

• The file path arrives on stdin; read it with jq. There is no ${filePath}

• Most projects need 3–5 hooks. Start with auto-format, session checks, and protected files

• SessionStart stdout goes directly into Claude’s context; use it to inject live state

• PreToolUse prevents. PostToolUse reacts. Know which one you need before you write the hook

• CLAUDE.md sets the rules while Hooks enforces them

Resources

The companion repo for this issue is now live.

Every hook, every script, and the complete settings.json are organised by section: copy what you need and drop it into .claude/hooks/

For this issue, the repo includes:

• All seven production hook scripts

• The complete .claude/settings.json for PDFChat

• The event reference table

• A starter three-hook config you can add to any project in five minutes

Support Our Newsletter

Next: Coming Up Issues

The next issues in this Masterclass Series will cover:

• Claude Code Subagents Masterclass — Building your AI team

• Claude Code MCP Masterclass — Extending Claude’s capabilities

• Claude Code in Production — CI/CD, team configuration, enterprise deployment

Your hooks are the automation layer, while subagents are the delegation layer. Both take your setup towards a complete autonomous development pipeline.

What’s the first hook you wrote?

Reply to this email and tell me. I’ll share the most interesting ones in a future issue.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Hello, thank you for being part of our Claude Code Masterclass community.

We are now 78k members; it’s unbelievable, and I am grateful for every one of you.

Last Week In Claude Code is back.

The good news is that Claude Code has matured a lot since last issue.

The pace of breaking changes has slowed, workflows are more stable, and the updates that have shipped are mostly features you layer on top of what already works.

This issue covers everything significant that was released since Issue #3: late June through mid-July 2026.

I have tested what matters, skipped trivial additions or fixes, and organized it so you can get up to speed fast.

What Happened: Last Few Weeks?

#1) Claude Fable 5 — The Most Capable Model Anthropic Has Ever Released to the Public

Version: 2.1.170 — June 9, 2026

Anthropic released Claude Fable 5 — a Mythos-class model that they have made safe for general use. Their words: “Fable’s capabilities exceed those of any model we’ve ever made generally available.”

Mythos was previously only available to a small number of trusted organizations through Project Glasswing due to cybersecurity concerns.

Fable 5 is the first time that level of capability has been opened to the public.

How to Access It

claude update

Update to version 2.1.170 or later, and you will see Fable 5 in your model picker.

/model

What to Know

• Available on Max, Team, and Enterprise plans

• Uses usage credits — check your balance before running heavy tasks

• The usage limit keeps getting reset, so ensure you follow the updates before using it heavily.

My Take

This is the model to reach for on your hardest problems: architecture decisions, complex debugging, security-critical code reviews.

Tasks where you previously used ultrathink and still felt like something was missing.

#2) Claude Sonnet 5 & Subagents in Background — The Default Stack Changed

Two big changes were released back-to-back at the end of June.

Claude Sonnet 5 — New Default Model

Version: 2.1.197 — June 30, 2026

Sonnet 5 is now the default model in Claude Code. If you open Claude Code today without picking a model, you are running Sonnet 5.

What changed:

• 1M token context window — native, not an add-on

• 128k max output tokens

• Promotional pricing — $2/$10 per million tokens through August 31, 2026

At that price, with that context, this is the best value model Anthropic has put in Claude Code.

Subagents Now Run in the Background by Default

Version: 2.1.198 — July 1, 2026

This one changes how multi-agent work feels.

Before this, when Claude spawned a subagent, you waited. The main session sat there while the subagent ran.

Now subagents run in the background automatically.

Claude keeps working on other tasks while they run and gets notified when they finish. You can also view the agents by opening the agents panel.

Run this command

claude agents 

Background Agents :

• Claude no longer blocks waiting for a subagent to complete

• You see progress in claude agents while the main session stays active

• Background agents that finish code work in a worktree now automatically commit, push, and open a draft PR — without stopping to ask

These two together: a faster default model with 1M context, and subagents that don't block your session make parallel workflows significantly smoother.

#3) /fork, /subtask & Session Caps — Multi-Agent Just Got Guardrails

Version: 2.1.212 — July 17, 2026

Three changes in one release that affect how you manage parallel work.

/fork Now Creates a Background Session

/fork used to spin up an in-session subagent — it ran inside your current session, and you watched it work.

Now /fork copies your conversation into a new background session with its own row in claude agents, while you keep working in your current session.

The in-session subagent that /fork used to launch is now /subtask

Session-Wide Caps on WebSearch and Subagents

Runaway loops are now stopped automatically.

# WebSearch calls per session (default 200)
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200

# Subagent spawns per session (default 200)
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200

Run /clear to reset the budget mid-session.

MCP Tool Calls Auto-Background After 2 Minutes

A slow MCP tool call used to freeze your entire session. Now it moves to the background automatically after 2 minutes so your session stays usable.

# Change the threshold (milliseconds)
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000

# Disable entirely
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0

#4) Performance & Stability — July Cleaned Up a Lot

Versions 2.1.200 through 2.1.216 (July 3–20) shipped the heaviest round of performance and stability fixes since Claude Code launched.

7x Faster Tool Rounds

Version: 2.1.208 — July 14

Per-tool-call CPU overhead is now cached instead of rebuilt on every call: up to 7x faster at high MCP tool counts. Update, and it works automatically.

Multiple Memory Leaks Fixed

Version: 2.1.208 — July 14

• MCP stdio server stderr accumulating up to 64 MB per server

• LSP documents staying open indefinitely — now capped at 50

• Async hook output retained after backgrounding

• Unbounded growth in SDK sessions from large tool-result payloads

If you have been hitting slowdowns in long sessions, this is the update.

Live Elapsed-Time Counter on Tool Calls

Version: 2.1.210 — July 14

Long-running tool calls now show a live ticking counter.

Before this, a slow tool call looked completely frozen with no indication it was still running.

/verify and /code-review Now Manual Only

Version: 2.1.215 — July 19

Claude no longer runs these on its own: you invoke them directly when you want them:

/verify
/code-review

Permission Mode Renamed to “Manual”

Version: 2.1.200 — July 3

Update your config to stay current:

{ "defaultMode": "manual" }

--safe-mode — Troubleshoot Without Your Config

Version: 2.1.169 — June 8

Start Claude Code with everything disabled: CLAUDE.md, plugins, skills, hooks, and MCP servers; all turned off in one flag.

claude --safe-mode

# Or via environment variable
export CLAUDE_CODE_SAFE_MODE=1

Useful when something is broken, and you need to isolate whether it is your configuration or Claude Code itself.

Before this, debugging a broken session meant manually disabling things one by one. Now you start clean in one command and add things back until you find the problem.

I shared a detailed review here on the Medium tutorial.

The plan from here is back to weekly issues, no more gaps. If there is a feature you want me to test and break down, reply to this email and let me know.

Tomorrow I will publish the Hooks Masterclass, which has been long-time coming — Thank you once again!

See you next week in Last Week In Claude Code

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

First, welcome to all new subscribers. We have finally made it to 39,000+. I am very grateful to each of you and am still overwhelmed by the support, pledges, and encouragement you have sent — Thank you once again.

This issue brings you the first article in the Claude Code Deep Dive series — Claude Code Ralph Loop Deep Dive

Every Claude Code session has the same hidden flaw; Claude stops when it thinks the job is done.

• Tests broken

• API half-implemented,

• Edge cases untouched

But it declares complete and exits. And the longer and more complex the task, the worse it gets.

There is a technique designed to fix this problem. You have probably heard the word “Ralph” thrown around.

It’s a simple idea that forces Claude to keep iterating until the work is genuinely completed.

Surprisingly, this technique has been used to ship entire projects overnight at a fraction of the actual cost.

In this newsletter, I’ll take you from understanding why Claude fails on complex tasks to building the full Ralph Loop system and running it on real projects.

We’ll cover the Ralph core mechanism, the PRD and memory architecture, and everything you need to put Ralph Loop to work.

Let’s start with the basics.

What is Ralph Loop?

Let me start with something that might surprise you.

Ralph Loop isn’t a framework, and it is not a sophisticated AI orchestration system. At the core, it’s a Bash while loop.

while true; do
  cat prompt.md | claude
done

The technique was created by Jeffrey Huntley

This childlike persistence is the philosophy behind the technique.

With Ralph Loop, Claude is no longer allowed to exit when it thinks it’s done. It’s forced to keep working until the task is truly finished.

The key insight is that Ralph Loop treats failure as expected, not exceptional.

Each iteration builds on the last. The AI sees what it did before, recognizes what’s still broken, and improves.

Why Claude Code Needs Ralph

Claude Code has a limitation that most developers don’t recognize until they’ve hit it repeatedly.

It operates in single-pass mode.

Even though Claude reasons extremely well, it stops as soon as it believes the output is “good enough.”

The model has what you might call an implicit execution budget. Once it feels like it’s done reasonable work, it wraps up and exits.

The problem is that “ good enough”, according to Claude, often isn’t good enough.

I’ve seen this pattern dozens of times:

• Claude builds a feature, declares it complete, but the edge cases are broken

• Claude writes tests, says they pass, but they don’t actually run

• Claude implements an API, marks it done, but forgot error handling

It believes it’s finished, but it’s making that judgment based on what the code looks like, not whether it works.

Another problem that makes this worse is the context rot.

As the conversation with Claude gets longer, the context window fills up. The model’s reasoning quality degrades as it has to juggle more information.

This is why the single-pass approach fails for complex tasks.

By the time Claude reaches the end of a big feature, its context is bloated with attempts, errors, and fixes. The quality of its reasoning has degraded.

Ralph Loop solves both problems:

1. Forces verification — Claude can’t exit until it proves the work is done

2. Fresh context — Each iteration starts clean, avoiding context rot

Core Mechanism

Let me break down how Ralph Loop works.

The Anthropic plugin uses the stop hook. This is a feature in Claude Code that runs whenever Claude finishes responding and tries to end the session.

Here’s the flow:

1. You give Ralph your prompt and a completion promise (like “DONE” or “COMPLETE”)

2. Claude works on the task

3. Claude tries to exit

4. The stop hook intercepts the exit

5. It scans the output for the completion promise

6. If no promise is found, it feeds the same prompt back to Claude

7. Claude sees its previous work in the files and improves it

8. Repeat until the completion promise appears

The magic happens in those state files at the bottom.

• prd.json — Contains your task list with passes: true/false flags. Claude reads this to know what’s done and what’s left.

• progress.txt — Short-term memory. Claude appends learnings after each iteration. The next iteration reads this to avoid repeating mistakes.

• agents.md — Long-term memory. Patterns and knowledge that persist beyond the current sprint.

When Claude starts a new iteration, it reads these files and sees the code it wrote. It sees what passed and what failed, and it sees notes from previous iterations.

This is what makes Ralph Loop more than just “run it again.” Each iteration is informed by all previous iterations.

Completion Promise

The completion promise is how Ralph knows when to stop.

You define a specific word or phrase — typically “DONE” or “COMPLETE”. Claude must output this wrapped in a specific format:

<promise>COMPLETE</promise>

The stop hook scans for this pattern. If it finds it, the loop exits. If not, the loop continues.

This creates a contract between you and Claude:

• You define what “done” means (clear criteria in your prompt)

• Claude works until those criteria are met

• Claude signals completion with the promise

• Ralph verifies and exits

The promise should represent actual completion. Your prompt needs to define what must be true before Claude outputs the promise.

Bad prompt:

Build a todo API. Output COMPLETE when done.

Good prompt:

Build a REST API for todos.

Requirements:
- CRUD endpoints for todos
- Input validation
- Error handling
- Tests with 80% coverage

Run tests after implementation. 
Only output <promise>COMPLETE</promise> when ALL tests pass.

The second prompt gives Claude binary criteria that can be verified.

What Ralph Loop Is NOT

Before we go deeper, let me clear up some misconceptions.

1. Ralph is not the Anthropic plugin.

The plugin is convenient, but it’s a simplified implementation. It doesn’t fully reset context between iterations the way the original bash loop approach does. For simple tasks, the plugin works fine. For complex projects, you’ll want the full approach.

2. Ralph is not magic.

It amplifies whatever you feed it. Good planning and clear criteria produce great results. Vague prompts produce expensive loops that go nowhere.

3. Ralph is not a replacement for thinking.

You still need to design your tasks, write clear criteria, and review the output. Ralph automates the iteration cycle, not the engineering judgment.

4. Ralph is not always the right tool.

Some tasks need human judgment at every step. Some tasks are one-shot and simple. Ralph is ideal for complex, multi-step work that has verifiable completion criteria.

Ralph Architecture

1) PRD (Product Requirements Document)

Everything starts with the PRD.

Before you run a single iteration, you need a clear definition of what you’re building. The PRD is the definition that guides every Ralph Loop iteration.

Most developers get it wrong: they try to write the PRD themselves.

I don’t do that.

Generate it through a conversation with Claude.

Here's a PRD generator prompt you can use:

I want to build [DESCRIBE YOUR FEATURE/PROJECT].

Interview me about this. Ask 3-5 clarifying questions about:
- Target users
- Core functionality
- Technical requirements
- Success criteria

After I answer, generate a PRD with:
- Project overview
- User stories (who does what, why)
- Feature requirements
- Success criteria (binary, testable)
- Technical stack
- Out of scope (what we're NOT building)

Key principle: Every success criterion must be binary and testable.

Not “the UI should look good” — that’s subjective. Instead: “the dashboard loads in under 2 seconds,” or “all buttons have hover states,” or “accessibility score is 90+.”

2) Task List (prd.json)

The PRD describes what you’re building. The task list breaks it into atomic pieces.

This is where Ralph Loop gets its power.

Instead of asking Claude to build an entire feature in one shot, you give it a sequence of small, focused tasks. Each task completes in one iteration with a fresh context.

The format follows Anthropic’s recommendation from their long-running agents documentation:

{
  "projectName": "Todo API",
  "tasks": [
    {
      "id": "US-001",
      "title": "Set up project structure",
      "acceptanceCriteria": [
        "package.json exists with dependencies",
        "TypeScript configured",
        "npm run build succeeds"
      ],
      "passes": false
    },
    {
      "id": "US-002", 
      "title": "Create todo database schema",
      "acceptanceCriteria": [
        "todos table with id, title, completed, created_at",
        "Migration runs successfully",
        "Schema matches specification"
      ],
      "passes": false
    },
    {
      "id": "US-003",
      "title": "Implement GET /todos endpoint",
      "acceptanceCriteria": [
        "Returns array of todos",
        "Supports pagination",
        "Tests pass for endpoint"
      ],
      "passes": false
    }
  ]
}

The passes: false flag is crucial. As Ralph completes each task, it sets this to true. The loop continues until all tasks pass.

Task sizing is critical. Each task must:

• Complete in ONE iteration

• Fit comfortably in the context window

• Have verifiable acceptance criteria

• Result in a working, committable change

If a task feels big, split it. “Build authentication” is too big. Split into: “Add users table” → “Create signup endpoint” → “Create login endpoint” → “Implement JWT tokens” → “Write auth tests.”

3) Memory System

Ralph Loop has memory, both short-term and long-term.

Short-term memory: progress.txt

This file tracks what happened during the current sprint.

After each iteration, Claude appends:

• What was implemented

• What files were changed

• Any learnings or patterns discovered

• Blockers encountered

The next iteration reads this file. It knows what the previous iteration did, what worked, and what didn’t.

## Iteration 3 - 2024-01-15 14:32

**Task:** US-003 - Implement GET /todos endpoint

**Implemented:**
- Created routes/todos.ts
- Added GET /todos with pagination
- Added tests for endpoint

**Files Changed:**
- src/routes/todos.ts (new)
- src/routes/index.ts (updated)
- tests/todos.test.ts (new)

**Learnings:**
- Pagination requires offset and limit params
- Need to handle empty results case

**Next:** US-004 - POST endpoint

Long-term memory: agents.md

This is permanent knowledge. Things that should persist beyond the current sprint.

You can have agents.md files in any folder. Claude reads them when working in that folder. They’re like sticky notes for future iterations (and future sprints)

# Project Patterns

## API Routes
- All routes use Express Router
- Validation middleware goes before handler
- Error responses follow { error: string, code: number } format

## Testing
- Use vitest, not jest
- Mock database with in-memory SQLite
- Each test file needs afterEach cleanup

## Gotchas
- Don't use `any` type - breaks type checking
- Always await database operations
- Rate limiting middleware must be first

The memory system is why Ralph gets smarter over iterations instead of repeating mistakes. Each iteration learns from the last.

4) Feedback Loop System

Without feedback loops, Ralph Loop is just expensive guessing.

Claude needs automated ways to verify its own work.

It can’t just look at code and decide it’s correct — it needs to run tests, check types, and execute builds, which is the real verification.

Build verification into every prompt:

After implementing:
1. Run `npm run typecheck` — fix any errors
2. Run `npm run lint` — fix any warnings  
3. Run `npm test` — all tests must pass
4. Run `npm run build` — must compile

Only mark task complete when ALL checks pass.
If any fail, debug and fix before continuing.

Feedback types and what they catch:

For backend work, types + tests + build are usually sufficient.

For frontend work, add browser automation. Claude can’t “see” a UI by reading code. It needs to render pages and interact with elements to verify they work.

The feedback loop creates self-correction. Claude writes code, runs checks, sees failures, fixes them, runs checks again.

Ralph Execution

There’s a right way and a wrong way to start using Ralph Loop.

The wrong way: install the plugin, fire off a complex prompt, go to sleep, wake up to chaos.

The right way: progress through levels, building understanding at each stage.

Jeffrey Huntley, the creator of Ralph, puts it simply: “Don’t start with the jackhammer. Learn the screwdriver first.”

The screwdriver is a manual single runs while the jackhammer is an overnight autonomous operation.

You need to master each level before moving to the next.

Each level teaches you something you can't learn at the next level.

Level 1: Manual Single Runs (The Screwdriver)

Start here with every new project.

At Level 1, you run one iteration at a time and watch everything.
You see what Claude does, what it gets right, what it gets wrong.

Run Level 1:

# Option 1: Direct command
cat prompt.md | claude

# Option 2: Using the plugin with max-iterations 1
/ralph-loop "your task" --completion-promise "DONE" --max-iterations 1

After each iteration:

• Read the code Claude wrote

• Check if it was committed properly

• Verify the prd.json was updated

• Look at progress.txt entries

• Run the tests yourself

Then run the next iteration.

What you’re learning at Level 1:

• How Claude interprets your prompts

• What patterns does your codebase trigger?

• Where Claude gets confused

• How long does each iteration take?

• What the token cost looks like

• Whether your criteria are clear enough

When to move to Level 2:

• You’ve run 10+ manual iterations

• You understand the flow completely

• You can predict what Claude will do

• You know what success looks like

• You know what failure looks like

Level 2: Attended Loops (Power Drill)

At Level 2, you let Ralph run multiple iterations

/ralph-loop "your task" --completion-promise "DONE" --max-iterations 10

Every few iterations, you look at:

• Is it picking tasks in the right order?

• Are commits happening after each task?

• Is progress.txt being updated?

• Are the tests actually passing?

• Any strange patterns emerging?

The key at Level 2 is catching problems early.

What you’re learning at Level 2:

• How the loop handles your specific codebase over time

• What failure patterns look like in your setup

• How quickly issues compound if not caught

• What is your actual token cost per task

• Whether your max-iterations is set appropriately

When to move to Level 3:

• You’ve run 3-5 attended loops (50+ total iterations)

• No surprises in the last 2-3 runs

• You trust the setup

• You know exactly what to check in the morning

• You have a recovery plan if things go wrong

Level 3: Unattended Overnight (Jackhammer)

The goal is to set it running before bed, wake up to completed work.

But you only get here after mastering Levels 1 and 2.

The overnight checklist:

Before starting an unattended run:

• PRD is complete and reviewed

• All tasks are atomic with clear criteria

• Feedback loops built into prompt (tests, types, lint)

• Max iterations set (30-50 for overnight)

• Git branch is clean and ready

• Notification system configured (optional but helpful)

• You know what “success” looks like in the morning

Morning review process:

1. Check prd.json — how many tasks passed?

2. Read progress.txt — any errors or blockers?

3. Review git log — are commits sensible?

4. Run tests manually — do they pass?

5. Test the feature yourself — does it work?

Expect 80-95% completion on a good run. Some edge cases always need human attention.

The goal isn’t perfect code but 8 hours of work done while you slept, with 1-2 hours of cleanup in the morning.

Setting up notifications:

You can add a notification when Ralph completes:

# Simple approach: notify after loop exits
/ralph-loop "task" --max-iterations 30 --completion-promise "DONE" && \
  notify-send "Ralph complete" || notify-send "Ralph failed"

Some developers set up WhatsApp or Slack notifications using simple scripts. Useful if you want to check progress before morning.

Ralph Practical Examples

Different projects need different approaches. Here are four patterns that work for specific use cases.

Pattern 1: The Feature Builder

Building new features from a PRD

This is the classic Ralph Loop use case. You have a feature to build, you break it into tasks, and Ralph builds it piece by piece.

Prompt template:

You are an autonomous coding agent working on this project.

Your task:
1. Read prd.json to find the highest priority task where passes is false
2. Implement that single task
3. Run tests to verify: npm run typecheck && npm test && npm run build
4. If tests pass, update prd.json to set passes: true
5. Append progress to progress.txt
6. Commit your changes with a descriptive message

Only work on ONE task per iteration.

When ALL tasks in prd.json have passes: true, output <promise>COMPLETE</promise>

Example project: REST API with 15 endpoints

• Task 1-3: Project setup, database, basic structure

• Task 4-10: Individual endpoints (one per task)

• Task 11-13: Validation, error handling, edge cases

• Task 14-15: Documentation, final tests

Expected: 15-20 iterations, 2-4 hours unattended

Pattern 2: Test-Until-Green

Improving test coverage on existing code

You have code that works but lacks tests. Ralph writes tests until coverage hits your target.

Prompt template:

Your task: Improve test coverage for this codebase.

Current coverage: Check with `npm run coverage`
Target coverage: 80%

Process:
1. Run coverage report to identify untested code
2. Write tests for the most critical untested function
3. Run tests to verify they pass
4. Check new coverage percentage
5. Append progress to progress.txt

Only write tests for ONE function per iteration.

Output <promise>COMPLETE</promise> when coverage reaches 80% or higher.

What makes this pattern work:

• Clear binary goal (coverage >= 80%)

• Claude can verify progress with each iteration

• Natural small units (one function = one iteration)

• Built-in feedback loop (coverage report)

Expected: Varies by codebase. 10-30 iterations typically.

Pattern 3: Multi-Persona Review

Best for: Code quality and production readiness

Instead of just building, Claude rotates through different reviewer personas. Each persona catches different issues.

Prompt template:

You are reviewing and improving this codebase by rotating through personas.

Personas:
1. Code Reviewer: Check for bugs, edge cases, code quality
2. Solution Architect: Check structure, dependencies, patterns  
3. QA Engineer: Check test coverage, error handling
4. Security Reviewer: Check for vulnerabilities, input validation
5. Front End Dev: Check UI/UX, accessibility, responsiveness

For each iteration:
1. Select the next persona in rotation
2. Review the codebase from that persona's perspective
3. Identify ONE issue to fix
4. Fix the issue
5. Commit with message: "[Persona] - description of fix"
6. Log the review in progress.txt

Continue until ALL personas complete 2 full cycles finding no issues.

When that condition is met, output <promise>COMPLETE</promise>

Why this works:

Different personas catch different problems.

• Code reviewer sees bugs.

• Security reviewer sees vulnerabilities.

• QA engineer sees missing tests.

Rotating through all of them creates comprehensive coverage that single-pass reviews miss.

Expected: 15-30 iterations for thorough review

Pattern 4: Proof of Concept Validator

Best for: Quickly validating ideas, testing tech stacks

You want to see if an idea works before committing to full implementation. Ralph builds a rough version fast.

Prompt template:

Build a proof of concept for: [IDEA]

Tech stack: [YOUR CHOICES]

This is a POC, not production code. Priorities:
1. Core functionality works
2. Happy path is complete  
3. Basic error handling
4. Demonstrates the concept

NOT priorities (skip for now):
- Comprehensive tests
- Edge case handling
- Production security
- Perfect code quality

Tasks:
1. Set up project structure
2. Implement core feature
3. Add basic UI (if applicable)
4. Verify it works end-to-end

Output <promise>COMPLETE</promise> when the POC demonstrates the core concept working.

When to use this pattern:

• Validating a new architecture

• Testing if a tech stack works for your use case

• Building a demo for stakeholders

• Exploring a new API or service

Key difference: Lower quality bar. You’re not building production code. You’re answering the question “Does this approach work?”

Expected: 5-10 iterations for basic POC

Choosing the Right Pattern

You can also combine patterns. Build with Feature Builder, then polish with Multi-Persona Review.

Final Thoughts

Ralph Loop is simple at its core - a while loop, a stop hook, and a completion promise.

But mastery requires:

• Understanding the fundamentals

• Building the right architecture

• Progressing through the levels

• Choosing the right pattern

Resources

PS: I launched the Claude Code Masterclass Git repo, where I will be adding all these code snippets and templates for quick and easy access.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Hello, thank you for being part of our Claude Code Masterclass community.

We are now 28k+ members (and I’m honestly blown away by your support, your pledges, and the incredible energy you’ve brought) — I’m grateful for every single one of you!

I am working day and night to deliver the best practical Claude Code education material.

Last week brought some useful Claude Code updates: a command to chat while Claude works, voice mode now rolled out to everyone (I built a full app with it), a 1 million context window for Opus and Sonnet, and a diagrams feature that might replace Canva for technical visuals.

What Happened Last Week In Claude Code?

#1) /btw Command — Chat While Claude Works

Claude Code /btw lets you ask side questions while Claude is working on a task.

If you’ve been mid-task, watching Claude work through a complex operation, and suddenly have a question, you either wait or interrupt.

The /btw command fixes this.

How It Works

/btw <question>

For example:

/btw what does retry logic do?

Claude opens an overlay with the answer. Your main task continues running in the background.

Press Space, Enter, or Escape to dismiss it and return to your session.

Key Features

• Runs in parallel — Your main task doesn’t pause or wait

• Overlay response — Answer appears in a pop-up, not inline

• No history pollution — The side question doesn’t get added to your main conversation context

• Single-turn only — You get one response, no back-and-forth

• No tool access — The response comes from Claude’s knowledge and current session context

Requirements

Available in Claude Code version 2.1.72 and later.

claude --version
claude update

I tested /btw with real examples and documented the setup and use cases.

You can learn more here — I Tried (New) Claude Code /btw Command (Now You Can Chat As You Code)

#2) /voice Full Test — I Built a Complete App With Voice

Anthropic rolled out Claude Code /voice to all users. I put it through a real build.

Last week I introduced /voice, but didn’t have access. Now I do — and I built a food ordering system entirely with voice.

The Build

• Backend: FastAPI with menu and order endpoints

• Frontend: Vanilla JavaScript to display the menu and place orders

This forced me to dictate real code, handle multiple files, and see how fast voice coding is.

How It Works

Type /voice to toggle it on.

• Push-to-Talk: Hold Space, speak, release. Your words stream in real-time at your cursor.

• Hybrid Prompts: Type half a prompt, hold Space to voice the messy middle, keep typing.

Fix the auth middleware in [hold Space] — the token validation 
is failing silently when the expiry timestamp is malformed, 
it should throw a proper 401 [release] — and add a test for it.

What I Found

The transcription picked up “manual endpoint” instead of “menu endpoint” — but Claude understood the intent and generated the correct code.

25 lines of clean backend code with proper type hints. The frontend came together just as fast.

What You Get

• No extra cost — Voice transcription doesn’t count against rate limits

• Cross-platform — Works on macOS, Linux, and Windows

• No cloud dependency — Runs locally inside your Claude Code session

Voice mode is now available to everyone. Check your Claude Code welcome screen.

You can learn more here — I Finally Tested Claude Code /voice — It’s Faster than Typing (Don’t Waste Time)

#3) 1 Million Context Window — Opus 4.6 & Sonnet 4.6

Anthropic added a 1-million-context window to Opus 4.6 and Sonnet 4.6.

This is now available by default for Max, Team, and Enterprise plans.

What Changed

• Opus 4.6 — 1M context window by default (previously required extra usage)

• Sonnet 4.6 — Also gets 1M context

• Output tokens — Opus 4.6 now outputs 64k tokens by default, up to 128k max

1 million tokens is roughly 700,000 words or about 2,500 pages of text.

You can now:

• Load entire codebases into a single session

• Work with massive documentation without truncation

• Maintain longer conversation history without compaction

Who Gets It

• Max plan — Yes

• Team plan — Yes

• Enterprise plan — Yes

• Pro plan — Check your settings

Version

Available in Claude Code 2.1.75 and later.

You can learn more here — Anthropic Adds 1 Million Context Window to Opus 4.6 & Sonnet 4.6

#4) Diagrams & Charts — I Tested 21 Prompts (Goodbye Canva)

Claude can now create complex diagrams and charts. I tested 21 prompts, from simple to complex.

The results were impressive.

One Line Prompt

Show me how a JWT authentication flow works from login to protected API access

Claude generated a complete visual diagram. This will change how I approach technical content.

What I Tested

Flowcharts & System Architecture

• CI/CD pipeline from commit to production

• Microservices order flow for e-commerce

• AWS serverless architecture for real-time chat

• Three-tier web architecture with caching and CDN

• Kubernetes container orchestration

Data Visualizations

• Performance benchmark bar charts (Python, Go, Rust, Node.js)

• Cloud costs pie chart by service category

• JavaScript framework popularity line chart

Database & Data Flow

• Event sourcing and CQRS for banking systems

• Social media ERD (users, posts, comments, followers)

• Real-time analytics pipeline with Kafka and Spark

Algorithm & Concept Explainers

• Binary search tree balancing

• OAuth 2.0 authorization flow

• DNS resolution step by step

Interactive Explainers

• JavaScript garbage collection

• Neural network backpropagation

• Hash map collision handling

• SQL vs NoSQL decision tree

For developers, technical writers, and content creators — this is what you need.

No more switching to Canva or Figma for technical diagrams. One prompt, instant visual.

You can learn more here — Claude Can Now Create Complex Diagrams — I Tested 21 Prompts (Goodbye Canva!

Finally, this newsletter belongs to all of us. If there’s something that can make it better or something you don’t like, please let me know.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Hello, thank you for being part of our Claude Code Masterclass community.

We are now 21k+ members (still overwhelmed by your support, your pledges, and good vibes) — it’s unbelievable, and I’m grateful for every one of you!

I am working day and night to deliver the best practical Claude Code education material.

Last week brought some major Claude Code updates: a framework to test if your agent skills work, Ultrathink made a comeback, native voice input, and a way to run subagents without burning tokens.

What Happened Last Week In Claude Code?

#1) Skill-Creator Plugin — Finally Test If Your Agent Skills Work

Agent skills are notorious for fooling you into believing they work — but sometimes they fail, and the next day they work fine.

Anthropic released the Skill-Creator plugin — a testing framework to measure and refine your agent skills.

What It Does

• Evals — Define test prompts and expectations, then check if outputs match

• Benchmarks — Track pass rate, elapsed time, and token usage

• A/B Comparisons — Blind testing between skill versions

• Description Optimizer — Improves skill triggering accuracy

Two Types of Skills

• Capability Uplift Skills — Help Claude do something the base model can’t do consistently (PDF, DOCX, PPTX creation)

• Encoded Preference Skills — Document your team’s workflows so Claude follows your process every time

Real Results

Anthropic tested the PDF skill on non-fillable forms:

• Test With Skill Without Skill Pass Rate 5/5 (100%) 2/5 (40%)

• The skill clearly adds value where the base model fails.

Installing the Plugin

# Add the marketplace
/plugin marketplace add anthropics/skills

# Install skill-creator
/plugin install skill-creator@anthropic-agent-skills

I tested the PDF skill on a job application form and documented the entire process — what worked, what broke, and how the plugin measures it.

You can learn more here — Claude Code Skill-Creator Measures If Your Agent Skills Work

#2) Ultrathink Is Back — Version 2.1.68

A fresh Claude Code update reintroduced Ultrathink, changing how you manage thinking effort.

What Changed in 2.1.68

• Opus 4.6 now defaults to medium effort for Max and Team subscribers

• Opus 4 and 4.1 are gone from the first-party API — users are moved to Opus 4.6

• Ultrathink is back after being removed in an earlier release

High effort on every prompt was overkill. Renaming a variable doesn’t need deep thinking.

Medium effort handles 90% of daily tasks. But that other 10% — architecture decisions, complex debugging, security-critical code — needs more.

That’s where Ultrathink makes sense.

Effort Levels

Method Effort Level Duration Default (2.1.68) Medium Permanent /model → High High Permanent ultrathink High One turn only

How Ultrathink Works

Type ultrathink before your prompt. Claude switches to high effort for that one turn, then returns to your default.

It only works if your current effort is medium or low. If you’re already on high, it does nothing.

My Test

I gave Claude Code the same debugging task: Node.js API with a race condition.

• Medium effort: Identified the cause, suggested a fix.

• Ultrathink: Walked through the entire request lifecycle, found two separate issues (the race condition + a token expiry edge case), and outlined a testing strategy.

From my findings, Medium gives you the answer. Ultrathink gives you the answer, plus things you didn’t ask about.

You can learn more here — Claude Code Ultrathink Is Back In New Update (I Just Tested It)

#3) Native /voice Mode — Stop Typing, Start Talking

Claude Code introduced voice mode last week. You can now use the /voice command.

How It Works

Type /voice to toggle it on.

• Push-to-Talk: Hold Space, speak, release. Your words stream in real-time at your cursor.

• Hybrid Prompts: Type half a prompt, hold Space to voice the messy middle, keep typing.

Fix the auth middleware in [hold Space] — the token validation 
is failing silently when the expiry timestamp is malformed, 
it should throw a proper 401 [release] — and add a test for it.

What You Get

• No extra cost — Voice transcription doesn’t count against rate limits

• Cross-platform — Works on macOS, Linux, and Windows

• No cloud dependency — Runs locally inside your Claude Code session

Roll Out

It’s rolling out to ~5% of users first.

Check your Claude Code welcome screen — if you’re in the rollout, you’ll see a note confirming voice mode is available.

If not, as in my case above, the rollout is expanding over the coming weeks. I’ll run a full build test to show you how it works.

You can learn more here — Claude Code Voice Is Here /voice (You Can Now Talk & Stop Typing)

#4) Ollama Subagents & Web Search — Run Parallel Agents at No Cost

You can now run Claude Code subagents and web search using Ollama cloud models — without burning your Anthropic tokens.

One Command to Launch

ollama launch claude --model minimax-m2.5:cloud

Works with any model on Ollama’s cloud.

Subagents in Action

I built an expense tracker using three parallel subagents:

• frontend-ui-expert — HTML, CSS, vanilla JS (11.4k tokens)

• Backend agent — FastAPI routes and models (11.0k tokens)

• Project structure agent — Files and README (10.8k tokens)

All three ran simultaneously. Project completed in minutes.

Then I spun up three more subagents to audit the code. They found real issues:

• CORS vulnerability (allow_credentials=True with wildcard origins)

• Deprecated datetime. utcnow

• Float for monetary values instead of Decimal

Web Search Works Too

Subagents can research topics in parallel:

spawn research agents to find the latest FastAPI 0.115 release features,
research best practices for expense tracker API design, and summarize
Python REST API security guidelines

Three research agents returned structured tables with actionable recommendations.

Recommended Models

Not all Ollama models support subagents and web search. These three work:

• minimax-m2.5:cloud

• glm-5:cloud

• kimi-k2.5:cloud

This setup works best for prototypes and learning. For production work or sensitive codebases, stick with the paid API.

But for experimenting without watching your bill — or when Anthropic has an outage — this is the move.

You can learn more here — How I’m Running Claude Code Subagents & Web Search (At No Cost)

Finally, this newsletter belongs to all of us. If there’s something that can make it better or something you don’t like, please let me know.

See you in the next issue of Last Week In Claude Code.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Hello, thanks for being part of our Claude Code Masterclass community. We are now headed to 20k members — I am eternally grateful for every one of you!

I have updated the quick updates to be Last Week in Claude Code so that I can write a summary of updates once a week.

This conforms to our original content structure, as I shared in the Claude Code Masterclass Introduction.

In this series, I will be sharing the Claude Code updates from the previous week in a quick summary after I have tested and documented them.

The goal is to save your time and help you learn new Claude Code updates faster.

Quick Note: I apologize for taking longer to release the Hooks Masterclass. As you may already know, testing and creating comprehensive content takes a lot of time, especially for hooks.

I’m also slightly behind the publishing calendar, but I am doing my best to keep up with the pace at which things are changing.

What Happened Last Week In Claude Code?

#1) /simplify & /batch — Code Reviews Just Got 10x Faster

Version: 2.1.63

Claude Code introduced two commands to simplify code reviews - /simplify and /batch

/simplify — Automated Code Quality Pass

Spins up parallel agents that review your code against your CLAUDE.md standards and fix issues automatically.

What it catches:

• Dead code and commented-out blocks

• Inefficient patterns and code smells

• CLAUDE.md rule violations

• Duplicate logic across files

My test: 69 lines of messy code → 33 clean lines in 1 minute 29 seconds

/batch — Parallel Migration Engine

Plans and executes large-scale migrations using isolated agents in git worktrees.

/batch migrate src/ from Jest to Vitest
/batch migrate src/ from CommonJS to ES modules

How it works:

1. Scans your directory and creates a migration plan

2. Shows you exactly what will change before touching code

3. Spins up isolated agents per folder

4. Each agent tests its work before opening a PR

I tested both commands on a real project and documented everything — the setup, the results, and what Claude actually changed.

You can learn more here — How I’m Using Claude Code /simplify & /batch to x10 My Code Reviews

#2) Auto-Memory (MEMORY.md) — Claude Now Remembers Your Project

Claude now builds and maintains its own memory as it works with you, quietly taking notes on your build commands, code style, architecture decisions, and the bugs you solved together.

How It Works

• Auto-enabled — No configuration needed, works out of the box

• Claude writes it — You don’t touch MEMORY.md; Claude does

• 200-line limit — Only the first 200 lines load at session start

Where it’s located:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Main index, loaded every session
├── debugging.md       # Detailed debugging notes
└── api-conventions.md # API decisions

CLAUDE.md vs MEMORY.md — What's the Difference?

Both load at session start. Together, they give Claude full context before you start coding.

Managing Memory

Use the /memory command to:

• Toggle auto-memory on/off

• Open your memory folder

• Access user and project memory files

Turn It Off (If Needed)

// Disable for one project (.claude/settings.json)
{ "autoMemoryEnabled": false }

// Disable globally (~/.claude/settings.json)
{ "autoMemoryEnabled": false }

// Force off in CI environments
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

I tested auto-memory from scratch — created a project, worked a session, closed it, and came back cold. Claude remembered everything.

You can learn more here — Anthropic Just Added Auto-Memory to Claude Code — MEMORY.md (I Tested It)

#3) Remote Control — Code From Your Phone

Control your local Claude Code session from any device — phone, tablet, or another browser.

Your laptop stays at your desk running Claude Code. Remote Control creates a secure connection so you can control that session from anywhere.

This is not Claude Code on the web (which runs in Anthropic’s cloud).

Remote Control runs on your machine:

• MCP servers stay active

• Project context stays intact

• Your filesystem is fully available

• All your tools and permissions persist

Three Ways to Connect

1. Session URL — Copy from terminal, paste in any browser

2. QR Code — Press spacebar in terminal, scan with Claude mobile app

3. Session List — Find it at claude.ai/code with a green status dot

Requirements

• Pro or Max plan (not Team/Enterprise yet)

• Authenticated via claude.ai (API keys won’t work)

• Workspace trust accepted

I documented the setup, the flags, multi-device workflows, and managing multiple projects — so you’re ready when it rolls out to you.

You can learn more here — I Tried (New) Claude Code Remote-Control (Before You Waste Your Time)

Finally, this newsletter belongs to all of us. If there’s something that can make it better or something you don’t like, please let me know.

See you in the next issue of Last Week In Claude Code.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Since the first issue of Claude Code Masterclass Introduction, I’ve been overwhelmed by your response — encouragement, support, and so many new pledges. Thank you.

Your feedback made one thing clear: you want structure.

This issue brings you the second article in the Claude Code Masterclass series. — Mastering CLAUDE.md File

Every Claude Code session starts the same way — Claude knows nothing about your project.

• It doesn’t know your tech stack.

• It doesn’t know your folder structure.

• It doesn’t know that you prefer tabs over spaces or that your team uses a specific branch naming convention.

So you should explain your project every single time.

“This is a FastAPI project. We use SQLAlchemy for the database. Tests are in the /tests folder. Run pytest to execute them. Oh, and we follow PEP 8 with 100-character lines.”

This creates a problem of constantly explaining your project details, and that is the problem CLAUDE.md solves.

CLAUDE.md is a markdown file that gives Claude persistent memory about your project. Create it once, and Claude reads it automatically at the start of every session.

In this guide, I’ll take you from creating your first CLAUDE.md to building pro-level configurations that compound with hooks and subagents.

We’ll cover the hierarchy system, the anatomy of a well-structured file, and everything you should know about the CLAUDE.md file.

Let’s start with the basics.

What is CLAUDE.md?

Most developers think of CLAUDE.md as a documentation file, which is wrong!

CLAUDE.md is a configuration file that becomes part of Claude’s system prompt.

This distinction matters because Claude treats system-level instructions differently from user prompts. Here is an illustration :

When you put instructions in CLAUDE.md, Claude follows them more strictly than anything you type in the chat.

Why Claude Will Ignore Your CLAUDE.md

Claude Code wraps your CLAUDE.md with a system reminder that tells Claude to ignore irrelevant content.

The actual wrapper looks like this:

<system-reminder>
  IMPORTANT: this context may or may not be relevant to your tasks. 
  You should not respond to this context unless it is highly relevant to your task.
</system-reminder>

This means if you stuff your CLAUDE.md with instructions that aren’t universally applicable, Claude will ignore them.

This is why “less is more” is the best trick when creating your CLAUDE.md file.

Mental Model

Think of CLAUDE.md as three things:

1. Project Memory — Claude remembers your setup across sessions

2. Operational Boundaries — Rules Claude won’t break

3. Context Primer — Claude starts informed, not blank

When you understand this mental model, you stop treating CLAUDE.md like a README since it’s the best leverage configuration point you have in Claude Code.

CLAUDE.md Hierarchy System

CLAUDE.md files can live in multiple locations, and Claude reads them in a specific order.

Understanding this hierarchy lets you create global rules that apply everywhere and project-specific rules that apply only where needed.

Three Levels

How Each Level Loads

Let’s look at a practical example:

Monorepo Setup

my-monorepo/
├── CLAUDE.md                    # Monorepo-wide rules
├── apps/
│   ├── web/
│   │   └── CLAUDE.md            # Frontend-specific rules
│   └── api/
│       └── CLAUDE.md            # Backend-specific rules
├── packages/
│   └── shared/
│       └── CLAUDE.md            # Shared library rules
└── tests/
    └── CLAUDE.md                # Testing conventions

The nested files only load when Claude accesses files in those directories. This keeps your main context lean until Claude needs that specialized knowledge.

File Naming Options

• CLAUDE.md — Standard, commit to git, share with the team

• CLAUDE.local.md — Add to .gitignore, personal overrides

Use .local.md for personal preferences, you don’t want to push to the repo.

Anatomy of a Great CLAUDE.md

A well-structured CLAUDE.md answers three questions for Claude:

• WHAT — The tech stack, project structure, key files

• WHY — The purpose of the project, what each part does

• HOW — Commands to run, workflows to follow, conventions to respect

Core Sections

# Project Context

Brief description of what this project is and your working philosophy.

## About This Project

Tech stack, architecture pattern, key dependencies.

## Key Directories

- `src/` — Source code
- `tests/` — Test files
- `docs/` — Documentation

## Commands

```bash
npm run dev      # Start development server
npm run test     # Run tests
npm run build    # Production build

Standards

• Coding conventions

• Testing requirements

• Commit message format

Workflows

Step-by-step processes for common tasks.

Notes

Gotchas, warnings, things Claude should know.

Here is an example:

### A Real Example

Here's a CLAUDE.md for a FastAPI project:

```markdown
# Project Context

When working with this codebase, prioritize readability over cleverness. 
Ask clarifying questions before making architectural changes.

## About This Project

FastAPI REST API for user authentication and profiles. 
Uses SQLAlchemy for database operations and Pydantic for validation.

## Key Directories

- `app/models/` — Database models
- `app/api/` — Route handlers
- `app/core/` — Configuration and utilities
- `tests/` — Test files (fixtures in `tests/conftest.py`)

## Commands

```bash
uvicorn app.main:app --reload  # Dev server
pytest tests/ -v               # Run tests
alembic upgrade head           # Run migrations

Standards

• Type hints required on all functions

• pytest for testing

• PEP 8 with 100-character lines

• All routes use /api/v1 prefix

Notes

• JWT tokens expire after 24 hours

• Rate limiting is 100 requests/minute per IP

• Never commit .env files

The best approach is to keep each section focused. If a section grows too long, it’s a sign you should move that content to a separate file and reference it

Claude.md Content

Most CLAUDE.md problems come from including too much, not too little. It’s a delicate balance that can only be measured by my four rules :

1) 150-200 Instruction Limit

Research shows that frontier LLMs can reliably follow approximately 150-200 instructions.

Beyond that, instruction-following quality degrades; not just for new instructions, but uniformly across all of them.

Claude Code’s system prompt already contains ~50 instructions.

That leaves you with roughly 100-150 instructions before Claude starts ignoring things.

This is why less is more, since every unnecessary instruction reduces Claude’s ability to follow the important ones.

Always include:

• Project overview (1-2 sentences)

• Tech stack and key dependencies

• Essential commands (build, test, run)

• Directory structure (key folders only)

• Critical conventions that cause bugs if missed

Include if universally applicable:

• Branch naming conventions

• Commit message format

• Testing requirements

• Deployment process

Never include:

• Sensitive information (API keys, credentials, connection strings)

• Detailed code style guidelines (use a linter instead)

• Task-specific instructions (use separate files)

• Everything Claude could figure out by reading your code

Move to separate files:

• Database schema details

• Complex workflow procedures

• Architecture deep-dives

• Onboarding documentation

2) Progressive Disclosure

Instead of adding everything into CLAUDE.md, keep task-specific instructions in separate files and tell Claude where to find them.

As an example :