Claude Code Multi-Agent Commands: A Beginner's Guide

8/10/2025

A Beginner's Guide to Using Multi-Agent Commands in Claude Code

Hey there! So, you've probably been hearing a lot about AI coding assistants. Maybe you're already using one, getting it to write some boilerplate code or explain a tricky function. But what if I told you there's a way to level up from just having a single AI assistant to managing a whole team of them? That's what's happening right now with multi-agent setups, & honestly, it's a game-changer.

I’ve spent a ton of time recently diving deep into Claude Code, moving away from other tools because the power you get with multiple agents is just on another level. It’s less like having a conversation with a chatbot & more like being a manager with a team of AI developers ready to tackle complex tasks in parallel.

This guide is for you if you're a beginner who's curious about this whole "multi-agent" thing. We're going to break down what it is, how to get started, & why it's about to become your favorite way to code.

First Things First: Getting Set Up

Before we can command our AI team, we need to get the basics in place. The whole experience is built around a terminal interface, which might sound like a step back, but it's surprisingly powerful.

Install the VS Code Extension: Your journey starts here. Search for the Claude Code extension in the Visual Studio Code marketplace. It also works with Cursor, but for our purposes, we'll focus on the VS Code integration. Don't expect a fancy UI; it's basically a launcher that makes it easy to open Claude Code instances in different panes of your IDE. This is key because you can have multiple agents working on different parts of your codebase at the same time.
Initialize Your Project: Once you have the extension, open a terminal in your project's root directory & run the command
1/init
. This creates a
1claude.md
file. This file is super important because it acts as a summary of your codebase & a memory bank for the project. It helps Claude understand the context of your repository, which speeds things up immensely in future sessions.
Fix Terminal Quirks: One of the first things you'll notice is that Shift+Enter might not create a newline like you're used to. It's a small annoyance, but an easy fix. Just run
1/terminal-setup
, & Claude will sort it out for you.
Get Used to
1/clear
: This is probably the most important habit to build. Your AI agents work within a fixed "context window," which is a limit on how much information they can remember at one time. Long, rambling conversations eat up this context (and your tokens, which can cost money), degrading performance. Before you start a new, distinct task, just type
1/clear
to wipe the slate clean. Trust me, it saves a lot of headaches.

The Core Idea: What Are Subagents?

Okay, so what's the magic behind multi-agent commands? It's a feature called "subagents."

The core insight is this: instead of having one massive AI context trying to juggle everything—reading files, searching the web, writing code, running tests—you can delegate tasks to specialized subagents. Each subagent gets its own separate context to work in. It does its job, figures out what's important, & then sends a compressed summary back to the main "lead" agent.

Think about it like this: if you asked a single person to research a topic, write a report, & create a presentation all at once, they'd be slow & inefficient. But if you have one person doing research, another writing, & a third on design, they can work in parallel & just share the key findings with each other. That's EXACTLY what Claude Code does.

This approach has some HUGE benefits:

Parallel Processing: You can run multiple tasks at the same time.
Separation of Concerns: Each agent focuses on one thing, leading to better results.
Reduced Context Pressure: The main chat window doesn't get clogged up with thousands of lines of raw search results or file contents, which keeps the lead agent sharp & efficient.
Better Answers: Internal evaluations have shown that this multi-agent system just flat-out delivers more correct answers than a single agent.

Your First Multi-Agent Commands: Simple but Powerful

Ready to try it out? The commands themselves are surprisingly simple & use natural language.

The main commands you'll use are

use subagent

multiple subagent

Let's start with a classic use case: exploring a new codebase. Imagine you've just joined a project & need to get the lay of the land. Instead of manually opening dozens of files, you can delegate the work.

Try a prompt like this:

Using 4 subagents, explore the backend, frontend, configuration, and tests in parallel. Each subagent should read the relevant files and generate a report on its assigned section.

What happens next is pretty cool. Claude Code will spin up four separate subagents. One will dig into your

/backend

directory, another into

/frontend

, a third will analyze config files, & the last will look at the tests. Each does its work independently. Once they're done, the main agent you're talking to will summarize all their findings into a single, coherent overview. This is an AMAZING way to get up to speed on an unfamiliar repository.

Here are a few other ideas for beginners:

Running Tests: "Use 3 subagents to run the unit tests, integration tests, & end-to-end tests simultaneously."
Refactoring: "Use subagents to refactor the
1UserService
&
1ProductService
modules. For each, rename the
1_internal
methods to be truly private & add JSDoc comments to all public methods."
Researching an Issue: "Use a subagent to search the web for best practices on implementing OAuth2 in a Node.js Express server in 2025. Use the Context7 tool to find up-to-date API documentation."

Leveling Up: Creating Custom Slash Commands

Typing out

use subagent...

prompts over & over can get a little tedious. This is where custom slash commands come in. They let you wrap complex, multi-step workflows into a single, reusable command. It's like creating your own personal toolkit for your AI team.

Here’s how you do it. In your project's root, create a folder named

.claude/commands

. Inside that folder, you create markdown files (

.md

). The name of the file becomes the name of your command.

Let's create a

/bugfix

command. We know that when we're fixing a bug, we usually need to investigate errors, search for solutions, look at relevant documentation, & then propose a fix. We can automate that entire sequence.

Create a file named

.claude/commands/bugfix.md

& put this inside: