open/claude-code-agent-loop
1
0
Fork 0
Code Activity Actions

feat: initial companion repo for CC-001 Agent Loop

Browse source
This commit is contained in:
Kjell Tore Guttormsen 2026-03-30 10:36:26 +02:00
commit 06828d22f9
5 changed files with 510 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

40
CLAUDE.md Normal file
View file

@ -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.

69
README.md Normal file
View file

@ -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.

107
exercises/01-watch-the-loop.md Normal file
View file

@ -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).

148
exercises/02-control-the-loop.md Normal file
View file

@ -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).

146
exercises/03-design-for-the-loop.md Normal file
View file

@ -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)
<details>
<summary>Hint 1: Prompt structure</summary>
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)
</details>
<details>
<summary>Hint 2: Example prompt skeleton</summary>
```
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.
```
</details>
---
## 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