commit 06828d22f9ee252c50ecbdaec5fd8523a84607e1 Author: Kjell Tore Guttormsen Date: Mon Mar 30 10:36:26 2026 +0200 feat: initial companion repo for CC-001 Agent Loop diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e2a424f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,40 @@ +# The Agent Loop + +## What this project is + +A companion repo for the From AI to Chitta article on **The Agent Loop** +(concept ID: `CC-001`). It contains exercises that let you observe and +control Claude Code's core execution cycle. + +Article: https://fromaitochitta.com/the-agent-loop + +## How to use this + +1. Open Claude Code in this directory: `cd claude-code-agent-loop && claude` +2. Work through exercises in order: `exercises/01-watch-the-loop.md`, then 02, then 03 +3. Each exercise has a self-contained prompt you paste into Claude Code +4. Compare your output to the expected output described in each exercise + +## Code quality expectations + +- This is a learning repo. Clarity over cleverness. +- Every exercise must run without modification on a clean clone +- No external dependencies unless explicitly listed in the exercise +- If something does not work as expected, that is useful information: note it + +## Project structure + +``` +exercises/ Numbered exercises with prompts and expected output +CLAUDE.md This file: project instructions +README.md Overview for anyone who clones this repo +``` + +## Domain + +Claude Code Foundation + +## Memory + +Keep session notes in a local `MEMORY.md` (gitignored). This file +(CLAUDE.md) is for instructions. MEMORY.md is for state. diff --git a/README.md b/README.md new file mode 100644 index 0000000..edd12b6 --- /dev/null +++ b/README.md @@ -0,0 +1,69 @@ +# The Agent Loop + +Claude Code reads, thinks, acts, and repeats until your task is done. +This is the core pattern that makes it different from every other AI +coding tool. + +Companion repo for the article +[The Agent Loop](https://fromaitochitta.com/the-agent-loop) on From AI to Chitta. + +--- + +## What You Will Learn + +By working through the exercises in this repo, you will be able to: + +- Recognize the agent loop in action and understand what Claude is doing at each step +- Control the loop with Plan Mode, /rewind, and manual intervention +- Design prompts that give the loop clear goals and produce reliable results + +These are not theoretical outcomes. Complete the exercises and you will +see the loop working on your own tasks. + +## Prerequisites + +- Claude Code installed (`claude --version` prints a version) +- A Claude Pro, Team, or Enterprise subscription +- Basic comfort with the terminal (cd, ls, opening files) + +No npm install, no Docker, no build step. + +## Exercises + +| # | Exercise | What It Covers | +|---|----------|---------------| +| 01 | [Watch the Loop](exercises/01-watch-the-loop.md) | See the read-think-act cycle on a real task | +| 02 | [Control the Loop](exercises/02-control-the-loop.md) | Plan Mode, /rewind, stopping a runaway agent | +| 03 | [Design for the Loop](exercises/03-design-for-the-loop.md) | Write prompts that guide the loop effectively | + +Start at `exercises/01-watch-the-loop.md`. Each exercise links to the next. + +## How to Use This Repo + +**"Show me what it does":** Browse `exercises/` and read through +the prompts. Understand the pattern before you run anything. + +**"Let me actually do it":** Open Claude Code in this directory +and follow the exercises in order. Each one has an expected output +section so you know when you have succeeded. + +```bash +git clone https://git.fromaitochitta.com/fromaitochitta/claude-code-agent-loop.git +cd claude-code-agent-loop +claude +``` + +Then open `exercises/01-watch-the-loop.md` and paste the prompt into Claude Code. + +## Domain + +**Claude Code** - This repo is part of the Claude Code Foundation series on +From AI to Chitta. See the full series for related concepts. + +## About + +Built by [Kjell Tore Guttormsen](https://fromaitochitta.com) as +part of the From AI to Chitta project, exploring the intersection +of AI tools and inner development. + +MIT License. diff --git a/exercises/01-watch-the-loop.md b/exercises/01-watch-the-loop.md new file mode 100644 index 0000000..2ffcd81 --- /dev/null +++ b/exercises/01-watch-the-loop.md @@ -0,0 +1,107 @@ +# Exercise 01: Watch the Loop + +**Concept:** The Agent Loop (CC-001) +**Level:** Basic +**Time:** ~10 minutes + +--- + +## Objective + +Watch Claude Code execute a multi-step task from start to finish. +You will see the agent loop in action: Claude reads, thinks, picks +a tool, observes the result, and repeats until done. + +This is your first hands-on contact with the agent loop. No prior +experience with Claude Code required beyond having it installed. + +--- + +## Before You Start + +Confirm you have: + +- [ ] Claude Code installed (`claude --version` prints a version) +- [ ] This repo cloned and open in your terminal +- [ ] Started Claude Code in this directory (`claude`) + +--- + +## Instructions + +**Step 1:** Open Claude Code in this repo directory. + +```bash +cd claude-code-agent-loop +claude +``` + +**Step 2:** Paste this prompt into Claude Code: + +``` +Create a file called loop-demo.md that contains: + +1. Today's date and time +2. A list of all files in this directory with their sizes +3. The first 5 lines of README.md +4. A summary sentence describing what this repo is about + +Do not ask me any questions. Just do it. +``` + +**Step 3:** Watch the terminal output carefully as Claude works. + +You will see Claude make a series of tool calls. Pay attention to: +- Which tools Claude picks (Bash, Read, Write, Glob) +- The order it chooses to do things +- How it uses the output of one step to inform the next +- That you did not tell it which tools to use or what order + +**Step 4:** Read the generated `loop-demo.md` file. + +Check that it contains all four items from the prompt. Claude gathered +information from multiple sources (system clock, file system, file +contents) and synthesized them into one output file. + +--- + +## Expected Output + +After 15-30 seconds, you should see: + +- A new file `loop-demo.md` in the repo root +- It contains today's date (from a Bash call to `date`) +- It lists files with sizes (from `ls -la` or similar) +- It includes the first 5 lines of README.md (from Read tool) +- It ends with a summary sentence about the repo + +The exact content varies, but the structure should match. + +**How you know the agent loop worked:** +- Claude made 3-5 tool calls without asking you anything between them +- Each tool call built on information from the previous one +- The final file synthesizes data from multiple sources + +--- + +## What You Learned + +- **The loop is autonomous:** Claude decided the order and tools on its own +- **Each step informs the next:** The loop observes results before choosing the next action +- **The task, not the steps, is what you specify:** You said what you wanted, not how to get it + +--- + +## Clean Up + +Delete the generated file so the repo stays clean: + +```bash +rm loop-demo.md +``` + +--- + +## Next + +Ready to go further? Move to [Exercise 02: Control the Loop](./02-control-the-loop.md). diff --git a/exercises/02-control-the-loop.md b/exercises/02-control-the-loop.md new file mode 100644 index 0000000..a9cf4e0 --- /dev/null +++ b/exercises/02-control-the-loop.md @@ -0,0 +1,148 @@ +# Exercise 02: Control the Loop + +**Concept:** The Agent Loop (CC-001) +**Level:** Intermediate +**Time:** ~15 minutes + +--- + +## Objective + +Learn to steer the agent loop instead of just watching it. You will +use Plan Mode to preview what Claude intends to do before it acts, +and use /rewind to undo a wrong turn. + +Exercise 01 showed the loop running freely. This exercise shows you +the controls. + +--- + +## Before You Start + +Confirm you have: + +- [ ] Completed Exercise 01 (or understand the basic loop concept) +- [ ] Claude Code open in this directory + +--- + +## Part A: Plan Mode + +**Step 1:** Press `Shift+Tab` until the mode indicator shows **plan**. + +You should see the permission mode change in the bottom bar. In Plan +Mode, Claude will describe what it plans to do instead of doing it. + +**Step 2:** Paste this prompt: + +``` +Create a project structure for a simple blog: +- A folder called blog/ with index.html, style.css, and posts/ +- An about.html page +- A README.md explaining the structure +``` + +**Step 3:** Read Claude's plan. + +Claude will describe the files it would create, the structure, and +the content. It will NOT create anything yet. This is the plan. + +**Step 4:** If the plan looks good, type: + +``` +Go ahead, execute this plan. +``` + +Or press `Shift+Tab` back to a normal mode and re-send the prompt. + +Claude now executes, creating the actual files. + +**Why this matters:** For complex tasks where a wrong start wastes +time, Plan Mode lets you course-correct before any files are written. + +--- + +## Part B: Using /rewind + +**Step 1:** Give Claude an intentionally vague prompt: + +``` +Improve the blog project. +``` + +Claude will likely make some changes you did not expect or want. +That is the point of this exercise. + +**Step 2:** After Claude finishes, review what it changed. If the +changes are not what you wanted, type: + +``` +/rewind +``` + +This restores your context to the state before Claude's last action. +The files are unchanged (Claude did write them), but the conversation +context is rewound so you can try a different approach. + +**Step 3:** Now give a more specific prompt: + +``` +Add a navigation bar to index.html that links to about.html. +Do not change anything else. +``` + +Notice how specificity gives the loop better direction. + +--- + +## Part C: Stopping a Runaway Loop + +**Step 1:** Give Claude a deliberately open-ended task: + +``` +Make this blog production-ready. +``` + +**Step 2:** As Claude starts working (adding frameworks, build tools, +etc.), press `Escape` to interrupt. + +Claude stops mid-execution. You can then redirect: + +``` +Stop. I just want the HTML and CSS to be clean and valid. +No frameworks, no build tools. +``` + +--- + +## Expected Output + +After completing all three parts: + +- A `blog/` directory with `index.html`, `style.css`, `posts/`, `about.html`, `README.md` +- You experienced Plan Mode (preview before execution) +- You used /rewind to undo a vague prompt +- You interrupted a runaway loop with Escape + +--- + +## What You Learned + +- **Plan Mode previews:** Shift+Tab toggles Plan Mode, where Claude describes its plan before acting +- **/rewind undoes context:** It rolls back the conversation so you can try a different approach +- **Escape interrupts:** Press Escape to stop Claude mid-loop when it is going in the wrong direction +- **Specificity guides the loop:** Vague prompts produce unpredictable results. Specific prompts keep the loop on track. + +--- + +## Clean Up + +```bash +rm -rf blog/ about.html +``` + +--- + +## Next + +Ready to design prompts that work with the loop? Move to [Exercise 03: Design for the Loop](./03-design-for-the-loop.md). diff --git a/exercises/03-design-for-the-loop.md b/exercises/03-design-for-the-loop.md new file mode 100644 index 0000000..968b230 --- /dev/null +++ b/exercises/03-design-for-the-loop.md @@ -0,0 +1,146 @@ +# Exercise 03: Design for the Loop + +**Concept:** The Agent Loop (CC-001) +**Level:** Advanced +**Time:** ~20 minutes + +--- + +## Objective + +Design a multi-step task that takes advantage of the agent loop's +strengths. You will write a prompt that requires Claude to gather +information from multiple sources, make decisions based on what it +finds, and produce a structured output. + +This exercise has no step-by-step walkthrough. You get a scenario, +constraints, and success criteria. How you get there is up to you. + +--- + +## Before You Start + +Confirm you have: + +- [ ] Completed Exercises 01 and 02 +- [ ] Claude Code open in this directory +- [ ] Internet access (Claude will use WebSearch) + +--- + +## The Scenario + +You want to evaluate whether a specific open-source tool is worth +adopting for your workflow. Instead of spending an hour researching +manually, you will write one prompt that makes Claude do the research +for you. + +## Your Task + +Write a prompt that makes Claude: + +1. **Search** for information about a tool you are curious about + (pick any real tool: a CLI tool, a library, a framework) +2. **Read** the tool's documentation or README +3. **Compare** it against an alternative you already know +4. **Write** a structured evaluation to a file called `evaluation.md` + +The evaluation file must include: +- Tool name and what it does (one sentence) +- Three strengths +- Three weaknesses or limitations +- A direct comparison with the alternative +- A verdict: adopt, wait, or skip + +## Constraints + +- Your prompt must be a single message (no back-and-forth) +- Do not tell Claude which tools to use (let the loop decide) +- The output must be a single file, not multiple files +- Use Plan Mode first to preview, then execute + +## Success Criteria + +- [ ] Claude made at least 5 tool calls to complete the task +- [ ] The evaluation file exists and contains all required sections +- [ ] The strengths and weaknesses are specific (not generic praise) +- [ ] The comparison is direct, not just two separate descriptions +- [ ] The verdict gives a clear recommendation with reasoning + +--- + +## Hints (only if stuck) + +
+Hint 1: Prompt structure + +A good prompt for the agent loop includes: +- What to research (specific tool name) +- What to compare against (specific alternative) +- What output to produce (file name and structure) +- What NOT to do (no installation, no code generation) + +
+ +
+Hint 2: Example prompt skeleton + +``` +Research [tool X] and compare it to [tool Y] for [use case]. + +Search the web for recent reviews and the official docs. +Write an evaluation to evaluation.md with: +- One-sentence description of each tool +- 3 specific strengths of [tool X] +- 3 specific weaknesses of [tool X] +- Direct comparison table: [tool X] vs [tool Y] +- Verdict: adopt, wait, or skip, with reasoning + +Do not install anything. Do not write code. Research only. +``` + +
+ +--- + +## Reflection + +After completing this exercise, consider: + +- How many tool calls did Claude make? (Check the terminal output) +- Did the loop take any detours? Were they useful or wasteful? +- What would you change in your prompt to get a better result? +- How long would this research have taken you manually? + +The agent loop is most powerful when the task requires gathering +and synthesizing information from multiple sources. A single prompt +replaces what used to be 30 minutes of tab-switching and note-taking. + +--- + +## What You Learned + +- **Single-prompt, multi-step tasks** are where the agent loop shines +- **Output structure in the prompt** gives the loop a clear target +- **Plan Mode first** lets you verify the approach before committing +- **The loop handles the how:** You specify the what and the where + +--- + +## Clean Up + +```bash +rm evaluation.md +``` + +--- + +## What Comes Next + +You now understand the agent loop: what it is (Exercise 01), how to +control it (Exercise 02), and how to design tasks for it (Exercise 03). + +Next concepts to explore: +- **CC-002 Built-in Tools** - The specific tools the loop uses +- **CC-010 CLAUDE.md** - How to give the loop standing instructions +- **CC-006 Permissions** - How to control what the loop is allowed to do