How to create multiple subagents in Claude Code to complete the task.

Claude Code is a great tool, even if you're not a developer. But there are a lot of things that Claude Pro users typically never try.

One of those things is the ability to create multiple subagents simultaneously to accomplish your tasks, and that's a completely game-changing twist.

Don't treat Claude Code as a single agent!

The way most people use Claude Code looks like this: Open the terminal, give it a task, watch it read the file and make changes, wait for it to finish, then give it the next task. One agent, one job, sequentially from beginning to end.

This works well with most things. But it has a limitation, and that limitation becomes apparent when you're working with anything that has actual moving components. Building a new feature while writing tests. Refactoring a module while updating documentation. Exploring a codebase from three different angles to understand how things are connected. In the single-session model, all of that is a queue. Everything is waiting.

Another issue is context. The longer a single session runs, the more the context window fills with everything: file contents, intermediate inferences, search results, decisions made two hours prior. The model's attention span decreases as the stream lengthens. Quality degrades, initially subtly and then becoming noticeable.

Subagents address both of these issues simultaneously. Instead of one agent doing everything, your main session becomes the coordinator. It breaks down the work, delegating each part to a subagent, and each subagent runs in a separate context window with its specific task. They can run in parallel. When they complete, the main session receives their results and continues.

How to set up subagents in Claude Code

This is easier than you think. There are no special flags to pass or configuration files to search for. Subagents in Claude Code are just Markdown files located in a directory.

You have two places to put them. `~/.claude/agents/` is the global directory, meaning any Claude Code session on your machine can use any agent located there. The `.claude/agents/` directory inside a specific project is local to that project, which is useful if you want the agents committed to the repo and shared with your team.

Each agent is a single Markdown file with a YAML frontmatter block at the top and a system prompt in the body. Here's an example of a very basic agent:

--- name: swift-engineer description: Sử dụng agent này khi cần viết code SwiftUI views hoặc code mạng Swift. Gọi cho bất kỳ màn hình iOS, ViewModel hoặc công việc mạng async/await nào. model: claude-sonnet-4-6 tools: Read, Write, Glob --- Bạn là một kỹ sư iOS cấp cao chỉ viết bằng Swift. Tuân thủ nghiêm ngặt MVVM: views là ngu ngốc, logic nằm trong ViewModels, tất cả các cuộc gọi mạng đều sử dụng async/await. Trước khi viết bất cứ điều gì, hãy đọc cấu trúc dự án hiện có bằng Glob và khớp với bất kỳ quy ước nào đã có sẵn. Trả về danh sách mọi file bạn đã tạo hoặc sửa đổi.

The name is how you and Claude call it. The description is what really matters and determines how the main agent uses it. Write the description as a routing rule, specific about when to call it and what the return value is. Vague descriptions will lead to vague routing. "Use this agent when." followed by a specific condition is an effective pattern.

The tools field is a list of permissions. The test writer probably doesn't need to delete the file. The code reviewer probably shouldn't have write permissions. Locking the tools for each agent is one of the more useful things you could do here for security and logical reasons.

If you don't want to write the file yourself, Claude Code has a /agents command that opens an interactive manager. You describe what you want, Claude will write the agent configuration for you, and you choose the scope to save it. The descriptions it generates are usually better than what most people write manually on their first try.

Now, you simply need to ask Claude to perform a task that the agent is designed to do, and it will automatically route if the description is specific enough.

For parallel tasks, the prompt for the main agent is very simple. For example:

Tôi đang xây dựng một ứng dụng iOS với giao diện người dùng Swift và backend Swift Vapor. Khởi tạo 3 subagent song song: 1. Sử dụng subagent swift-engineer. Xây dựng màn hình đăng nhập và dashboard SwiftUI. 2. Sử dụng subagent backend-engineer. Xây dựng các API endpoint Vapor cho /auth/login 3. Sử dụng subagent test-writer. Viết các bài kiểm tra cho các API endpoint và Swift ViewModels.

Each subagent runs concurrently, in its own context, reporting back independently. The main session resumes when all three are complete. What was previously three sequential searches with an ever-expanding context stream is now three independent workers running simultaneously.

You will need some time to get used to it.

What binds all of this together is independence. If two parts of work need to share state, or one depends on the output of the other, they belong to the main thread. If they can operate without knowing about each other, they are potential candidates for a subagent. That boundary is usually quite clear once you pay attention.

However, there is a problem with this approach, and that is the use of tokens. Using multiple agents simultaneously will consume a lot of tokens, but don't worry. You can also use Claude Code for free by combining it with a local LLM, meaning you will never run out of tokens.