Agents

Agents are how Claude Code handles complex, multi-step tasks autonomously. Learn when and how to use them, and how to run tasks in parallel for maximum productivity.

What Are Agents in Claude Code?

In Claude Code, an "agent" is Claude operating in a mode where it can autonomously plan and execute multi-step tasks. Instead of you directing every single action, you describe a goal and Claude figures out the steps, executes them in sequence, and reports back with the result.

You have already been using agents without realizing it. Every time you ask Claude Code to do something that requires multiple steps—like "refactor this component and update all the imports"—Claude is acting as an agent. It reads files, plans the changes, makes edits, and verifies the result, all without you directing each step.

Agent vs. Chatbot

Understanding the difference is key to using Claude Code effectively:

Claude Code defaults to agent mode. When you give it a task, it does not just tell you what to do—it actually does it. This is the fundamental power of Claude Code compared to a regular AI chat interface.

How Agents Work

When you give Claude Code a complex task, it follows an agent loop:

The Reasoning Loop

What makes agents powerful is the feedback loop. Claude does not just execute a fixed plan—it adapts based on what it discovers. If it reads a file and finds the code is structured differently than expected, it adjusts its approach. If a command fails, it reads the error and tries a different strategy.

Observation: "The auth library exports a createClient function"
  → Adjust: "I'll use createClient instead of the init pattern"

Error: "Module not found: @/lib/supabase"
  → Fix: "The supabase client is at @/utils/supabase, let me update the import"

Test failure: "Expected 200 but received 401"
  → Debug: "The test needs an auth token, let me add a mock"

Running Tasks in Parallel

One of the most powerful features of Claude Code is the ability to run multiple agent instances simultaneously. Each instance works in its own context, tackling a separate task. This is like having multiple assistants working on different parts of your project at the same time.

How to Run Parallel Tasks

Open multiple terminal tabs or windows, navigate to your project in each, and launch Claude Code with different tasks:

# Terminal 1
$ claude "Write unit tests for the auth module"

# Terminal 2
$ claude "Update the API documentation in the README"

# Terminal 3
$ claude "Fix the CSS layout bug on the settings page"

Each instance operates independently. They can read the same files but if both try to edit the same file simultaneously, you may end up with conflicts. Plan your parallel tasks to target different files when possible.

Using Git Worktrees for Isolation

For maximum safety with parallel tasks, use Git worktrees. Each worktree is an independent working directory with its own branch, so parallel Claude instances cannot conflict with each other.

# Create worktrees for parallel tasks
$ git worktree add ../my-app-auth feature/auth
$ git worktree add ../my-app-docs feature/docs

# Terminal 1: work on auth in isolation
$ cd ../my-app-auth && claude "Implement OAuth login"

# Terminal 2: work on docs in isolation
$ cd ../my-app-docs && claude "Rewrite the API docs"

When to Use Agents vs. Direct Conversation

Not every interaction needs to be an agentic task. Here is a practical guide for when to let Claude operate autonomously versus when to have a back-and-forth conversation.

Use Agents For (Let Claude Work Autonomously)

• Well-defined tasks with clear success criteria ("add dark mode support")
• Repetitive multi-file operations ("rename userId to accountId everywhere")
• Code generation from specs ("build a REST API based on this schema")
• Testing ("write comprehensive tests for the payment module")
• Refactoring ("convert all class components to functional components")
• Research tasks ("audit all dependencies for security vulnerabilities")

Use Direct Conversation For

• Exploring options before committing ("what are the pros and cons of these two approaches?")
• Learning ("explain how this code works")
• Architecture decisions ("should we use a monorepo or separate repos?")
• Debugging with you in the loop ("help me figure out why this test fails")
• When the requirements are vague and you need to iterate on them

Example: Research 5 Competitors Simultaneously

Suppose you need to analyze how five competitor projects handle authentication. Instead of researching them one at a time, you can run five parallel Claude Code sessions.

$ mkdir competitor-research && cd competitor-research
$ mkdir competitor-{1,2,3,4,5}
$ claude /init

# Tab 1
$ cd competitor-1 && claude -p "Clone and analyze the auth
  implementation of github.com/example/project-a. Write a
  summary in analysis.md covering: auth strategy, libraries used,
  token management, and security measures."

# Tab 2
$ cd competitor-2 && claude -p "Clone and analyze the auth
  implementation of github.com/example/project-b..."

# (repeat for tabs 3-5)

$ claude "Read all five analysis.md files in the competitor-*
  folders and create a comparison matrix in comparison.md.
  Include a recommendation for our project."

What would have taken an afternoon of manual research is done in the time it takes Claude to clone and analyze five repositories—usually a few minutes.

Costs and Token Usage

Here are practical strategies to manage agent costs:

• Be specific in your instructions. "Add a login page with email and password fields using our existing form components" is cheaper than "add authentication" because Claude does not need to explore as many options.
• Break large tasks into smaller ones. Instead of "build the entire admin dashboard," try "create the admin layout component" first, then "add the users table," and so on.
• Use /compact regularly during long agentic sessions to reduce context size.
• Use -p for one-shot tasks that do not need a conversation. This avoids accumulating context across turns.

Agent Best Practices

• Commit before big agent tasks. Create a Git checkpoint so you can easily revert if something goes sideways.
• Give clear success criteria. "All tests should pass" or "the page should render without errors" gives Claude a way to verify its own work.
• Review the work. Even experienced users review agent output. Skim the diffs, run the tests, and spot-check the implementation.
• Interrupt early. If you see Claude heading in the wrong direction, press Ctrl + C immediately. It is cheaper to redirect than to let Claude finish something you will discard.
• Use CLAUDE.md. A well-written CLAUDE.md drastically reduces agent errors because Claude knows your project's conventions upfront.