⚡ The Three Fundamental Commands
Before setting up any loop system, you need to understand the three primitives Claude Code provides natively. They’re the building blocks of any cyclical automation. As Cole Medin puts it: "Loop engineering isn’t that complicated. I don’t even know if it deserves its own term."
🧱 The Three Primitives
/loop - Execution interval
Set an interval (e.g., every 5 minutes) for the agent to wake up and run a prompt. The most common use: monitor something external (GitHub issues, task queue) and act when there is work.
"Every five minutes, I’ll check this repo for new GitHub issues and take care of any that show up." - Cole Medin
/goal - Completion criteria
You define what "done" means. The agent works until it meets the criterion, with no fixed interval. Similar to the concept behind Ralph loops that went viral: work until it's done.
/routines - Scheduled jobs
Recurring scheduled jobs. Example: "Every hour, wake up, read the spec document, and execute the next pending task." It's the cron of the agent world.
"Every hour, I want you to wake up, check a broader spec document, and take care of the next task." - Cole Medin
💡 Practical Tip
In most cases, you only need the /loop with a plan.md. The other two are complementary tools. Don't overcomplicate things if the problem is simple.
📋 Creating the plan.md
O plan.md is the heart of any basic loop. It’s a simple Markdown file with a task list. The agent reads it, executes the first incomplete task, validates it, marks it as done, and sleeps until the next cycle. Cole Medin demonstrated this live: "I’m just using this as an example. These are the tasks we wanted to run incrementally."
📄 plan.md template
# Plano de Tarefas
## Contexto
Projeto: [nome do projeto]
Objetivo: [o que queremos construir/fazer]
Regras: uma tarefa por ciclo, validar antes de marcar
## Tarefas
- [ ] Tarefa 1: Criar estrutura base do projeto
Criterio: pasta criada, package.json init, deps instaladas
- [ ] Tarefa 2: Implementar componente principal
Criterio: componente renderiza sem erros
- [ ] Tarefa 3: Adicionar testes unitarios
Criterio: npm test passa com 0 falhas
- [ ] Tarefa 4: Configurar linting e formatacao
Criterio: npm run lint sem warnings
- [ ] Tarefa 5: Documentar API no README
Criterio: README com exemplos de uso
## Notas
- Nao pular tarefas
- Se uma tarefa falhar, reportar o erro e parar
- Cada tarefa deve ser auto-contida✓ Good plan.md
- ✓Atomic, independent tasks
- ✓Explicit validation criteria
- ✓Project context at the top
- ✓Markdown checkboxes for tracking
✗ Problematic plan.md
- ✗Vague tasks ("improve the code")
- ✗No "ready" criteria
- ✗Tasks that are too interdependent
- ✗10+ tasks in a single plan
🤔 Reflection Point
The plan.md is essentially a contract between you and the agent. The more explicit the validation criteria, the less likely the agent is to "think" it's finished when it isn't. Ask yourself: If I give this plan to an intern, will they know when each task is done?
🚀 The Prompt That Builds the Loop on Its Own
The most elegant part of the system: you don’t need to configure the loop manually. You ask Claude Code to load the loop skill and it configures the cycle on its own. Cole Medin showed exactly that: "You just tell it to use the loop skill. So there's a capability built right into the tool where it knows how to set up these loop systems based on what we ask it to do."
📦 Prompt Pack: Loop Setup
Copy and paste directly into Claude Code. The agent will set everything up on its own.
PROMPT 1 - Basic setup
Load the loop skill. Read plan.md in the project root.
Work through the tasks one at a time. For each cycle:
1. Find the first unchecked task
2. Execute it completely
3. Validate against the criteria listed
4. Mark it as done with [x] in plan.md
5. Schedule a quick wake-up for the next task
If all tasks are complete, report back with a summary.PROMPT 2 - With a defined interval
/loop 5m
Check plan.md. Execute the next unchecked task.
Validate the result. Mark complete if validation passes.
If validation fails, note the error in plan.md and move on.PROMPT 3 - What Cole Medin used (simplified)
/loop work through plan.md one task at a time"Eu nem escrevi esse prompt... ele escreveu o prompt: /loop work through plan.md one task at a time." - Cole Medin
💡 How It Works Under the Hood
When you say "load the loop skill," Claude Code:
- Recognizes that an internal loop capability exists
- Reads plan.md to understand the scope
- Executes the first pending task
- Validate the result
- Configures the
/loopautomatically wake up - Repeat until everything is marked as done
👁️ Automatic Wake-Up and Monitoring
Wake-up is the mechanism that turns a single run into a real loop. After completing a task, Claude Code schedules the next cycle on its own. "It sets up /loop itself. If we scroll down after it runs and validates the first task, we’ll see it resuming with a /loop wake-up."
Reading plan.md
First cycle
The agent reads the file, identifies it as a “sequential task list,” and finds the first unmarked task.
Execution + Validation
Real-world work
Executes the task, runs the tests or checks defined in the criteria, marks [x] in plan.md.
Automatic Wake-Up
Continuity
The agent schedules a /loop wake up with the prompt it wrote itself: "work through plan.md one task at a time". In the next cycle, repeat from step 1.
Conclusion
End of loop
When all tasks are marked, the agent stops scheduling wake-ups and reports the final result.
⚠️ Important Limitation
The terminal needs to stay open throughout the process. If you close the terminal, the loop dies. This is different from a daemon or background service. Cole Medin warns: "Desde que nosso terminal esteja aberto e o Claude Code esteja em execução, ele consegue cuidar disso de forma autônoma." This means: no terminal, no loop.
🔧 Context and Best Practices
The basic loop is simple, but it has pitfalls that can sabotage the result if you're not careful. The most dangerous one: context bloat. In a loop, everything runs in the same session. Each cycle accumulates more context, and eventually the LLM gets overloaded.
✓ Best Practices
- ✓Short tasks (1–2 files per cycle)
- ✓Automatable validation criteria
- ✓Plan.md with no more than 5-7 tasks
- ✓Monitor the session periodically
✗ What to Avoid
- ✗Loops with 20+ tasks in the same session
- ✗Leave it running for hours without checking
- ✗Tasks that depend on previous output
- ✗Ignore errors and let the loop continue
📊 Real-World Data
Cole Medin tested the basic loop and shared concrete results:
- 2 minutes to complete the first 2 tasks of a simple plan
- Automatic the agent wrote its own wake-up prompt
- Sequential one task per cycle, without trying to do everything at once
"I came back a few minutes later, and the first two tasks were already done. So it had already gone through two loop iterations." - Cole Medin
🤔 Reflection Point
The basic loop is powerful for simple, sequential tasks. But notice: everything runs in a single session, with a single model, and without observability. For anything more complex, you'll need the features in the next sections (Archon, dashboard, model mix). The basic loop is the “Hello World” of loop engineering, not a production system.
❓ Questions and Limitations
The basic loop is the simplest form of loop engineering, but it raises questions you need to consider before investing time in this approach.
Open Questions
Does Boris really manage “tens of thousands of agents per day”?
Cole Medin openly questions: "Boris Cherny says there are days when he manages tens of thousands of AI agents at the same time. Seriously, is that actually practical? Will it scale?" The honest answer: probably, at Anthropic’s scale, yes. For you and me, not necessarily.
What if the loop gets stuck halfway through?
Without external state, a terminal crash loses all progress. The plan.md saves some of it (tasks already marked), but the session context is gone. That's why the next modules cover durability through an external database.
Is it worth the cost for simple tasks?
A loop of 5 simple tasks can cost tens of thousands of tokens just in orchestration overhead. If you can do the same thing with 5 direct prompts, the loop doesn't make financial sense. The real value comes from repetitive tasks where a human would be a bottleneck.
🎯 When the basic loop shines
- •Rapid proof of concepts
- •Mechanical task lists (refactoring, migration)
- •Learning and experimenting with loops
- •Prototyping before investing in heavier infrastructure
📝 Module Summary
Next Module:
3.2 - Deterministic Workflows with Archon: how to go beyond the basic loop with controlled processes and model mixing