/goal: Tell Claude When It Is Done
The /goal command is deceptively simple. You set a completion condition. Claude works across turns until that condition is met, then stops.
# In an interactive Claude Code session
/goal Write unit tests covering 95% of the authentication module
# Compound conditions work too
/goal Implement OAuth2 login with Google and GitHub. All existing tests must pass. No TypeScript errors.
While a goal is active, a live overlay panel shows elapsed time, number of turns completed, and cumulative token count. The overlay runs in real time without blocking your ability to type — you can interact with the session while Claude is working if you need to redirect it or provide context it is missing.
What makes /goal different from just giving Claude a task in a single message is that it creates a controlled loop. Claude writes code, runs tests, inspects failures, revises the code, and runs tests again — automatically, across as many turns as the goal requires. The completion condition is checked after each cycle. This is not a new capability in the underlying model; it is a harness change that lets the model apply its existing tool-use and reasoning capabilities over a longer trajectory without requiring you to manually re-prompt it.
I used /goal to write a Zod schema validation test suite covering edge cases I had been putting off for weeks. The goal ran for 41 minutes and 23 turns. It found three input patterns my initial schemas did not handle and fixed them before stopping. Total cost: $0.43 in API tokens according to /usage. That 41 minutes would have been three to four hours of my time, spread across three separate mornings of interrupted work.
The comparison to point-and-shoot prompting is stark. “Refactor the auth module” stops when Claude runs out of obvious things to do. “/goal Auth module refactored with no TypeScript errors and 90%+ test coverage” stops when the work is actually done. That distinction is what makes /goal a fundamentally different interface, not just a convenience wrapper.
Background Sessions: The Full Control Surface
Background sessions are not new to Claude Code, but the 2.1.x releases added enough configuration surface that they now behave like first-class agent deployments rather than a niche CLI trick.
# Start a simple background session
claude --bg "Audit the codebase for security issues in the auth module"
# Fully configured background agent
claude --bg --name "security-audit" --model claude-opus-4-7 --effort high --permission-mode auto --settings ./.claude/settings.json --mcp-config ./.claude/mcp.json "Complete the security review and output findings to SECURITY_REPORT.md"
# Resume a background session interactively
/resume
# Resume by specific session ID
claude --resume <session-id>
The --fallback-model flag is worth knowing for production workflows. If the primary model hits a rate limit or quota boundary, Claude Code falls back to the specified alternative instead of failing hard:
claude --bg --model claude-opus-4-7 --fallback-model claude-sonnet-4-6 "Refactor the payment processing module"
For repositories where git worktrees cause problems — monorepos with symlinks, certain CI-generated layouts, some Windows configurations — set "worktree.bgIsolation": "none" in your settings.json. Background sessions will then edit the working copy directly instead of creating an isolated worktree. This unblocks a significant class of production use cases that were painful before 2.1.143.
Empty idle background sessions auto-retire after five minutes. Sessions that finish their work but leave a background shell running move to “Completed” rather than “Running”. These distinctions matter when you are managing six sessions and need to know which ones are still doing something versus which ones have finished and are just consuming memory.
The v2.1.142 release added a set of flags that turn what used to be informal defaults into explicit, preservable configuration. All of these work in both claude and claude agents:
claude --add-dir ../shared-lib # Give Claude read access to a directory outside cwd
claude --settings ./.claude/prod.json # Use project-specific settings file
claude --mcp-config ./.claude/mcp.json # Attach specific MCP servers to this session
claude --plugin-dir ./.claude/plugins # Load project-specific plugins
claude --permission-mode auto # No prompts for safe file operations
claude --effort xhigh # Maximum reasoning depth for trust-boundary tasks
claude --dangerously-skip-permissions # Full bypass (use only in sandboxed environments)
The --add-dir flag solves a recurring pain point. Claude Code previously could not read files outside the current working directory without you changing directories first. With --add-dir, you can give an agent access to a shared library, a design system package, or a documentation directory outside the project root — without restructuring your project layout to accommodate it.
For multi-agent orchestration, these flags let you configure each dispatched subagent independently. A lead orchestrator running at --effort high can dispatch subagents with lower effort for mechanical tasks like formatting or renaming, controlling cost across the entire system. For patterns on structuring these systems, the multi-agent coordination guide covers orchestrator-worker architectures in detail.
Three Workflows That Changed How I Work
1. The Background Audit
Every Friday, I run a background audit against the week’s merged PRs. The agent reads the diff, checks for patterns from our CLAUDE.md security rules, and writes findings to a WEEKLY_AUDIT.md file. I come back Monday to a report rather than a vague sense that I should probably review something.
claude --bg --name "weekly-audit" --model claude-opus-4-7 --effort high --permission-mode auto "Read all changes merged this week. Cross-reference against .claude/rules/trust-boundary.md. Write WEEKLY_AUDIT.md with findings ranked by severity. Flag any payment or auth path changes explicitly."
2. The Completion Gate
Before any PR goes out, I set a /goal with the exact criteria from our definition of done. Not a checklist I run through manually. Not a reminder to check TypeScript. A condition Claude satisfies or keeps working:
/goal All TypeScript type errors resolved. All unit tests pass. No console.log statements remaining. ESLint reports zero errors on changed files.
Claude works through the list systematically. It does not stop until every condition is true. This replaced my pre-PR checklist habit, which I was reliably skipping under deadline pressure.
3. The Pinned Session
I keep one pinned session open in Agent View for the project I am actively shipping. It holds project context, MCP server connections, and permission settings — configured once, preserved across updates. When I need Claude for something quick, I jump into the pinned session instead of starting a cold context window. Auto-restart on updates means I get new Claude Code features without losing the session configuration.
The /usage Command: Real Cost Visibility
Starting in v2.1.149, /usage breaks down your token costs by category: skills, subagents, plugins, and MCP server calls. Before this update, the aggregate cost was visible but opaque — you could not tell whether a session’s cost was driven by MCP tool calls, recursive subagent spawning, or the main conversation. That distinction matters when you are optimizing a multi-agent workflow for cost efficiency.
For MCP-heavy workflows, the MCP servers guide covers patterns for keeping call counts reasonable. An agent that calls an MCP server 50 times in a session is often doing something that could be batched into 3–5 calls with better tool design. /usage makes that pattern visible instead of hiding it inside an aggregate number.
What to Do Right Now
Update to v2.1.149 or later: npm update -g @anthropic-ai/claude-code. Then run claude agents and look at what is actually running. Most developers are surprised to find sessions they backgrounded and forgot. Pin the ones that matter with Ctrl+T so they survive the next update cycle.
For any task that takes more than 20 minutes to specify, set a /goal with the completion criteria instead of a task description. The difference in outcome is consistent enough that I now default to /goal for anything beyond a single-file edit.
If you are building production workflows with background agents, read the new flag documentation before committing to an architecture. The --permission-mode, --fallback-model, and --add-dir flags together create a configuration surface that was not possible before May 2026. The agents you can build now are meaningfully more reliable than what shipped in April.
The CLAUDE.md templates, agent skill starters, and MCP server boilerplates for building these workflows are available at wowhow.cloud — pay once, configure once, ship reliably.
Comments · 0
Beta: comments are stored locally on your device and not visible to other readers.
No comments yet. Be the first to share your thoughts.