How to Use /goal and /loop in Claude Code for Autonomous Long-Running Workflows
Combine /goal and /loop in Claude Code to define completion criteria and set recurring schedules so your agent runs until the job is truly done.
What /goal and /loop Actually Do in Claude Code
Running a one-off task in Claude Code is easy. You type a request, Claude executes it, and you move on. But that model breaks down quickly when you’re dealing with something more complex — a codebase audit that needs to run until every critical issue is fixed, a data pipeline that processes batches on a schedule, or a test suite that keeps running until all failures are resolved.
That’s where the Claude Code workflow commands /goal and /loop come in. Together, they let you define what “done” actually means and keep your agent working autonomously until it gets there. This guide covers how each command works, how to combine them effectively, and how to avoid the most common mistakes when setting up long-running autonomous workflows.
Understanding Claude Code’s Slash Command System
Before getting into the specifics of /goal and /loop, it helps to understand how Claude Code’s slash command system works at a basic level.
Claude Code supports custom slash commands through a simple file-based mechanism. Commands are stored as Markdown files inside a .claude/commands/ directory in your project root. The filename becomes the command name — so goal.md maps to /goal, and loop.md maps to /loop.
Remy doesn't build the plumbing. It inherits it.
Other agents wire up auth, databases, models, and integrations from scratch every time you ask them to build something.
Remy ships with all of it from MindStudio — so every cycle goes into the app you actually want.
When you invoke a command, Claude Code reads the corresponding Markdown file and treats its content as a prompt injection, optionally incorporating any arguments you pass via the $ARGUMENTS placeholder. This makes slash commands essentially reusable prompt templates that you can version-control alongside your code.
Project-Level vs. User-Level Commands
Commands in .claude/commands/ are project-scoped — they’re available only within that project. If you want commands to be available globally across all your Claude Code sessions, you can place them in ~/.claude/commands/ instead.
For most autonomous workflow setups, project-level commands make more sense. They let you define goals and loop logic that are specific to what that project actually needs to accomplish.
Why This Matters for Autonomous Workflows
The slash command system isn’t just a convenience shortcut. It’s the foundation for building repeatable, structured agentic behavior. Instead of retyping complex instructions every session, you define them once, parameterize them, and invoke them consistently.
/goal and /loop leverage this system to give Claude Code something it normally lacks in simple task mode: a persistent sense of direction and a mechanism to keep working until that direction is fulfilled.
Setting Up /goal: Defining What Done Looks Like
The most common failure mode in autonomous agent workflows isn’t technical — it’s definitional. The agent finishes what it thinks you asked for, stops, and you realize it only completed half the job. /goal solves this by giving Claude an explicit, checkable completion criterion.
Creating the /goal Command File
Start by creating the directory structure if it doesn’t already exist:
mkdir -p .claude/commandsThen create goal.md:
touch .claude/commands/goal.mdInside goal.md, you’ll define the prompt template that tells Claude how to interpret and track a goal. Here’s a practical starting template:
You have been given a specific goal to accomplish. Your job is not to stop until this goal is fully met.
Goal: $ARGUMENTS
Before starting, confirm you understand the goal and break it into verifiable sub-tasks. After completing each sub-task, check it off explicitly. When all sub-tasks are complete, run a final verification pass to confirm the goal has been achieved. Only then should you report completion.
If you encounter a blocker, describe it clearly and propose alternatives rather than stopping.Using /goal in a Session
Once the file is in place, you can invoke it like this:
/goal Fix all failing tests in the auth module and ensure coverage is above 80%Claude Code reads the command file, substitutes $ARGUMENTS with your goal text, and begins executing with that framing. The difference from a plain prompt is significant: Claude is now working from a structured definition that includes self-checking behavior and a clear termination condition.
Writing Effective Goals
A goal that’s too vague won’t help. “Improve the codebase” gives Claude nowhere to anchor. Goals that work well share three characteristics:
-
They’re verifiable. Claude should be able to confirm completion programmatically or through explicit observation. “All unit tests pass” is verifiable. “Make the code better” isn’t.
-
They have a scope boundary. Specify what’s in bounds and what isn’t. “Refactor the payment service without touching the database layer” is scoped. “Refactor everything” is not.
-
They include a success metric. Numbers help. “Reduce API response time below 200ms for the /search endpoint” gives Claude a concrete target.
Setting Up /loop: Running Until the Job Is Done
/goal gives Claude direction. /loop gives it persistence. The loop command creates a recurring execution pattern where Claude continues checking, working, and re-checking until the defined condition is met — or until you explicitly stop it.
Creating the /loop Command File
Create loop.md in .claude/commands/:
You are running in loop mode. Your task is: $ARGUMENTS
Follow this cycle:
1. Assess the current state against the task objective
2. Identify the next action to make progress
3. Execute that action
4. Verify the result
5. If the objective is complete, summarize what was done and stop
6. If the objective is not complete, go back to step 1
Do not stop between cycles unless you hit a genuine blocker that requires human input. If you're uncertain whether to continue, continue.Using /loop for Long-Running Tasks
A typical invocation looks like:
/loop Monitor the test suite output and fix any failures as they appearClaude will run through the loop cycle repeatedly — checking test output, fixing failures, verifying, and repeating — until the suite is clean.
You can also chain this with a time or iteration limit in your command file to add a safety ceiling:
...
6. If you have completed more than 20 cycles without reaching completion, stop and summarize your progress so far.Scheduled Loop Execution
For truly autonomous workflows — ones that run without you sitting at the terminal — you can combine Claude Code’s non-interactive mode with your OS scheduler.
Using cron (Linux/macOS):
# Run every hour
0 * * * * cd /path/to/project && claude --print "/loop Check for new data in /data/incoming, process it, and archive processed files" >> /var/log/claude-loop.log 2>&1The --print flag tells Claude Code to run non-interactively and print output without requiring a human in the loop. Combined with /loop, this gives you a fully autonomous scheduled agent.
Combining /goal and /loop for Autonomous Workflows
Used separately, each command solves part of the problem. Combined, they handle the full picture: a clearly defined destination (/goal) and a mechanism that keeps moving toward it (/loop).
Pattern 1: Goal-Directed Looping
The most common pattern is to use /goal to set the destination, then /loop to keep working until that goal is confirmed complete.
In practice, you’d structure this in a single session:
/goal All integration tests pass and no linting errors remain
/loop Run the test suite, fix any failures, run the linter, fix any errors, repeat until the goal is metClaude now has both a compass and an engine. It knows where it’s going and it knows to keep moving.
Pattern 2: Checkpoint-Based Looping
For longer workflows with multiple phases, you can break the goal into checkpoints and use /loop to drive each phase:
/goal Complete the three-phase data migration: (1) validate source data, (2) transform and load, (3) verify row counts match
/loop Work through each phase sequentially. Confirm each phase is done before moving to the next. After all three phases confirm success, stop.
This gives you auditability — Claude checks off phases explicitly and won’t skip ahead.
Pattern 3: Autonomous Monitoring
Some workflows aren’t about completing a one-time task — they’re about continuous monitoring and response. Here the loop runs on a schedule and the goal resets each cycle:
/loop Every cycle: check the error log at /var/log/app.log, identify any new critical errors since last check, create a GitHub issue for each one with relevant context, mark your last-checked timestamp. Run indefinitely.This is where combining Claude Code with cron or a task scheduler turns your agent into a persistent background worker.
Practical Examples of Autonomous Workflows
Example 1: Automated Code Review and Fix Loop
/goal All files in /src pass ESLint with zero errors and zero warnings
/loop Run ESLint on /src, identify the first file with errors, fix them, re-run ESLint on that file, repeat until cleanThis workflow progressively cleans the codebase file by file without requiring any manual intervention between runs.
Example 2: Test-Driven Bug Fixing
/goal The test suite in /tests/auth/ achieves 100% pass rate
/loop Run pytest on /tests/auth/, find the first failing test, read the relevant source code, fix the underlying bug, re-run just that test to confirm, then move to the next failureRather than fixing all tests simultaneously (which can cause interference), this drives Claude to work through failures sequentially and verify each fix before moving on.
Example 3: Documentation Generation Loop
/goal Every public function in /lib/ has a docstring following the Google Python style guide
/loop Find the next public function without a docstring, read its implementation and usage context, write an accurate docstring, add it, move to the next undocumented function. Stop when none remain.Documentation work is tedious and often neglected — this pattern handles it completely autonomously.
Example 4: Data Pipeline Processing
/loop Check /data/incoming/ for any .csv files. For each file found: validate the schema, transform to the target format, write to /data/processed/, move the original to /data/archive/ with a timestamp. Log each operation. Sleep 5 minutes between cycles.For this to run on a schedule, pair it with cron or a systemd timer.
Avoiding Common Mistakes
Mistake 1: Goals Without Exit Conditions
If your goal has no clear exit condition, Claude may loop indefinitely or stop at an arbitrary point. Always make sure the goal specifies what completion looks like from Claude’s perspective.
Bad: /goal Improve test coverage
Better: /goal Achieve 85% test coverage as reported by pytest-cov
Mistake 2: Loops Without Blockers Handling
Production code has edge cases. If Claude hits something it can’t handle and the loop doesn’t account for blockers, it might silently fail or spin in place. Build blocker handling into your loop command:
If you cannot make progress on the current step after two attempts, log the blocker to /var/log/claude-blockers.log with a description and skip to the next item. Don't halt the entire loop for a single failure.Mistake 3: No Output Logging in Non-Interactive Mode
When running Claude Code autonomously via cron or similar schedulers, you won’t see what’s happening in real time. Always redirect output to a log file:
claude --print "/loop ..." >> /var/log/claude-workflow.log 2>&1Review logs regularly, especially in the first few runs of a new workflow.
Mistake 4: Overly Broad File Access
Long-running autonomous agents that touch your filesystem can cause unintended changes if their scope isn’t constrained. Use Claude Code’s permission settings to limit which directories the agent can read and write. You can configure this in .claude/settings.json:
{
"permissions": {
"allow": ["Read(/src)", "Write(/src)", "Read(/tests)", "Write(/tests)"],
"deny": ["Write(/config)", "Write(.env)"]
}
}Mistake 5: Missing Verification Steps
A loop that doesn’t verify its own work can compound errors across cycles. Each iteration should include a check that confirms the previous action actually succeeded before moving on. Build explicit verification into your loop prompt.
How MindStudio Extends This for Production Workflows
Claude Code with /goal and /loop is a strong local setup for technical users. But there are scenarios where you need more infrastructure — distributed scheduling, integration with external services, handoffs between multiple agents, or visibility for non-technical stakeholders.
This is where MindStudio fits in. MindStudio is a no-code platform for building and deploying autonomous AI agents, and it’s directly compatible with Claude Code workflows through its Agent Skills Plugin.
The plugin (@mindstudio-ai/agent) is an npm SDK that gives Claude Code agents access to 120+ typed capabilities as simple method calls — things like agent.sendEmail(), agent.searchGoogle(), agent.runWorkflow(), and agent.generateImage(). It handles rate limiting, retries, and authentication automatically, so Claude can focus on the reasoning work rather than the infrastructure plumbing.
For long-running autonomous workflows specifically, MindStudio adds a few things that /goal and /loop alone can’t provide:
- Scheduled triggers — You can deploy background agents that run on a cron schedule without configuring your own server.
- Webhook and API triggers — External systems can kick off agent workflows automatically when specific events occur.
- Cross-agent orchestration — One agent’s output can feed directly into another agent’s input, enabling multi-stage pipelines with handoffs.
- Observability — Non-technical stakeholders can see what your agents are doing without reading log files.
If you’re building workflows that need to scale beyond a single developer’s machine, you can try MindStudio free at mindstudio.ai.
Frequently Asked Questions
What is the difference between /goal and /loop in Claude Code?
/goal defines the end state — it tells Claude what “done” looks like and sets the criteria for completion. /loop defines the behavior pattern — it tells Claude to keep cycling through assessment and action until the goal is met. They serve different purposes and work best when used together.
Are /goal and /loop built-in Claude Code commands?
Not as hardcoded commands. They’re implemented as custom slash commands using Claude Code’s file-based command system. You create them by adding Markdown files to .claude/commands/ in your project (or ~/.claude/commands/ for global availability). The flexibility here is actually an advantage — you can customize how they behave for your specific project needs.
Can Claude Code run loops without human supervision?
Yes. Using Claude Code’s --print flag combined with a cron job or system scheduler, you can run loop-based workflows fully autonomously. The key is to design your loop command with clear blockers handling and logging so you can review what happened after the fact.
How do I stop a /loop that’s running unattended?
For interactive sessions, Ctrl+C stops execution. For scheduled non-interactive runs, you kill the process via your OS (kill <PID>) or by removing/disabling the cron job. To add a programmatic exit, include a maximum cycle count or a sentinel file check in your loop command — for example: “If /tmp/stop-loop exists, halt immediately.”
How do I pass dynamic arguments to /goal or /loop?
Arguments are passed inline when invoking the command:
/goal $ARGUMENTSWhatever you type after /goal becomes the $ARGUMENTS value in your command file. You can also chain multiple pieces of context by structuring your command file to parse different sections of the argument string — though for complex multi-parameter setups, a more structured prompt template may work better.
What are the best use cases for /goal and /loop in Claude Code?
The highest-value use cases are ones where the task is well-defined but time-consuming and iterative:
- Fixing all failing tests in a suite
- Eliminating linting errors across a codebase
- Generating documentation for undocumented functions
- Processing batches of files as they arrive in a directory
- Running continuous monitoring and alerting on log files
- Executing multi-phase data migrations with checkpoints
Tasks that are ambiguous, require creative judgment, or have fuzzy completion criteria are better handled interactively.
Key Takeaways
Setting up autonomous long-running workflows in Claude Code with /goal and /loop comes down to a few core ideas:
/goaldefines the destination. Write goals that are verifiable, scoped, and metric-based. Vague goals produce vague results./loopprovides the engine. The loop keeps Claude working through cycles of assess-act-verify until the goal is confirmed complete.- Custom slash commands make both possible. Create
.claude/commands/goal.mdandloop.mdwith structured prompt templates that include$ARGUMENTSfor flexibility. - Non-interactive mode enables full automation. The
--printflag combined with cron jobs or schedulers turns Claude Code into a persistent background agent. - Always plan for failure. Build blockers handling, logging, and exit conditions into your commands before deploying autonomously.
For teams that need to go further — scheduling at scale, cross-agent orchestration, or connecting Claude Code workflows to external services — MindStudio provides the infrastructure layer that makes production-grade autonomous agents practical without building everything from scratch.
