How to use the /goal command in Claude Code for fully automated workflows.

The actual function of the /goal command in Claude Code

Most people use Claude Code interactively—you type a request, Claude responds, you review it, and request changes. That works well for simple tasks. But when you need Claude to handle something complex without constant monitoring, the /goal command completely changes the way things work.

The /goal command in Claude Code allows you to define high-level goals and measurable completion conditions. Instead of responding to a prompt and waiting, Claude Code continues to infer, perform actions, and check its own output until it determines the goal has been achieved. This is at the core of what makes it useful for automated workflows.

This guide covers how to write effective goals, how to define exit criteria so Claude knows when to stop, how to combine /goal with subagents to work in parallel, and how to avoid common mistakes that cause automated runs to go off track.

The /goal command is consistent with the architecture of Claude Code.

Claude Code is Anthropic's terminal-based programming agent. Unlike a chat interface, it has direct access to your file system, can execute shell commands, run tests, call APIs, and read error output—all without your intervention at each step.

The /goal command is specifically designed for the agentic layer of Claude Code. It switches Claude from response mode (waiting for your input) to scheduling and execution mode (working towards a defined outcome).

The difference between prompt and target

A typical Claude Code prompt has the task scope: 'Refactor this function to use async/await'. Claude performs the work, reports back, and stops.

The objective is defined based on the result: 'All unit tests pass, no TypeScript errors, and the CI process returns a green status'. Claude will continue working—fixing bugs, adjusting code, rerunning tests—until that condition is met or it determines that it cannot continue without human intervention.

That distinction is crucial. The goal is designed for processes that require multiple dependent, repeatable, and self-regulating steps.

When should you use /goal? When should you use a standard prompt?

Use /goal when:

1. The task requires multiple rounds of execution and debugging.
2. You want Claude to run automatically while you focus on other things.
3. The conditions for success can be clearly stated and verified through programming.
4. Are you running Claude Code in Headless or Auto mode?

Use the standard prompt when:

1. You need to closely monitor each step.
2. The task is a single, limited operation.
3. You are exploring or iterating interactively.

Set your first goal.

Basic syntax

The /goal command receives a simple description of your desired outcome:

/goal All tests in the /tests directory pass without modification to test files

That's the simplest form. Claude Code will understand this as its target and begin its work — reading the relevant files, running tests, diagnosing errors, writing fixes, and rerunning the tests to verify.

Write effective goals.

Vague goals produce inconsistent results. The more precisely you describe the outcome, the better Claude Code can assess whether that goal has been achieved.

Weak target :

/goal Make the app work better

Strong target :

/goal The Express server starts without errors, all /api routes return 200 status codes on the test suite, and no console.error calls appear in the output

The powerful version provides Claude with three verifiable conditions. It knows what "completion" looks like.

Principles for effective goal setting :

1. Use verifiable conditions — things that can be measured: number of tests, exit code, file existence, API response.
2. Avoid subjective language — "Clean," "optimized," or "better" are difficult for Claude to evaluate using programming.
3. Define scope — Tell Claude which files, folders, or systems are within scope. Without scope, Claude might work on things you didn't intend.
4. Include negative conditions if relevant — "Do not modify any files in /config" sets a clear boundary.

Determine exit criteria

Exit criteria are measurable conditions that indicate when Claude Code needs to stop. They are the most important part of any automated workflow.

Without clear exit criteria, the Claude Code could:

1. Stopping too early (before the task is fully completed)
2. Overdoing it (making unnecessary changes after the goal has been achieved)
3. An infinite loop attempts to fix something that is unfixable in the current context.

Types of exit criteria

Exit code

The simplest form: Claude runs a command and the target is met when it exits with code 0:

/goal `npm test` exits with code 0 and all 47 test cases show as passing

File state conditions

The objective is met when a specific file exists, contains specific content, or has been modified:

/goal A file named CHANGELOG.md exists in the root directory with entries for all commits since the last tag

API response conditions

Useful for integration work:

/goal GET /health returns {"status": "ok"} with a 200 response after the server starts

Combination conditions

You can combine multiple criteria:

/goal TypeScript compilation succeeds with zero errors, all Jest tests pass, and the build artifact exists at /dist/index.js

Set a limit on the number of repetitions.

One thing to note: Without constraints, Claude Code will continue trying if it thinks it can make progress. For complex tasks, you might want to specify a stopping condition in case the goal cannot be achieved:

/goal All database migration scripts run successfully in sequence. If any migration fails after three retry attempts, stop and report the failure with the full error output.

This prevents Claude from devoting his time to matters that require human intervention to resolve.

Run the /goal command in Headless and Auto mode.

The /goal command truly demonstrates its value when running Claude Code without interaction — as part of a CI process, a scheduled job, or an automated trigger.

Basics of Headless Mode

Claude Code supports Headless mode via the --headless flag (or equivalent environment variable), which eliminates interactive prompts and allows for fully automated execution. Combined with /goal, this gives you an agent that automatically executes a defined workflow from start to finish.

Examples of shell calls:

claude-code --headless --goal "All unit tests pass and the build artifact is generated at /dist"

Here's how you embed Claude Code into automation systems: A CI job calls Claude Code with a goal, Claude processes the task, and the job succeeds or fails based on the exit code.

Journaling and observation skills

When running in Headless mode, always log data. Claude Code outputs a detailed trace of its reasoning and actions—this is your audit trail if something goes wrong.

claude-code --headless --goal "." --log-file ./claude-run.log

Review the logbook after any non-trivial run to understand what Claude did, what he tried, and where he made decisions.

Connect to CI/CD pipelines

A common pattern is to trigger Claude Code via a CI step after tests fail on a feature branch:

1. The tests failed in the pipeline.
2. CI triggers a Claude Code step with the objective: 'Fix failing tests without changing the test files'.
3. Claude Code handles bugs and commits to bug fixes.
4. CI reruns the initial check to verify.

This works best for identifiable errors—data type errors, failed assertions, missing imports—where the fix is ​​clearly defined.

Combine the /goal command with subagents.

Claude Code supports multi-agent coordination, where a primary agent creates subagents to handle parallel or specialized tasks. The /goal command works at both levels.

What do subagents do?

Subagents are separate instances of Claude Code that the main agent can call to handle a specific piece of work. The main agent defines a sub-objective, delegates it, waits for the result (or runs other tasks in parallel), and integrates the output.

This is especially useful when:

1. Different parts of a task require different contexts.
2. Work can be parallelized (e.g., fixing bugs in different modules at the same time).
3. You want to isolate risky activities to a subagent that can be restarted if it fails.

How the main agent coordinates

A main agent running with the /goal command can divide the work as follows:

1. Analyze the overall objectives and identify independent sub-tasks.
2. Create subagents for each subtask, each with its own objective.
3. Monitor the results of the subagent as they complete.
4. Integrate output and verify top-level exit criteria.

You don't need to coordinate this yourself. Claude Code's planning layer automatically handles the splitting when you provide it with a sufficiently complex goal to require parallel work.

Practical example: Refactoring multiple modules

Let's assume your goal is:

/goal Migrate all database calls in /src to use the new ORM interface. All existing tests must still pass.

Claude Code can:

1. Create subagents for /src/users, /src/orders, and /src/products in parallel.
2. Each subagent handles its module independently.
3. The main agent collects results, runs the entire test suite, and handles any conflicts between modules.

This shortens a sequential process that can take hours into a much shorter, parallel process.