# Sub-agents and parallel work

> Split big tasks across KazoCode sub-agents, run them in their own Git worktrees, and run several tasks side by side in the Agent Workspace.

For large or parallel work, the agent can hand pieces of a task to **sub-agents**: separate agents with their own context that report back when they're done. You can also run several independent tasks at once in the **Agent Workspace**.

## Sub-agents

The agent starts sub-agents on its own when a task splits naturally, for example researching three parts of a codebase at once, or you can ask for it: "use three agents to update each service". A sub-agent:

- Starts with a fresh context, so the main conversation stays short.
- Gets only the tools it needs. A research agent can read but not edit.
- Follows the same [permissions](https://kazocode.app/docs/agent/permissions.md) and [hooks](https://kazocode.app/docs/customize/hooks.md) as the main agent.
- Runs in the foreground, where the main agent waits for it, or in the background while the main agent keeps working.

`/agents` lists every sub-agent in the chat with its result, and `/stop` stops all of them.

### Custom sub-agents

Define your own specialists as Markdown files with frontmatter in `.kazocode/agents/` (one project) or `~/.kazocode/agents/` (every project). Claude Code agents in `.claude/agents/` load too.

```md title=".kazocode/agents/reviewer.md"
---
name: reviewer
description: Reviews a diff for bugs and missing tests. Use after making changes.
tools: read_file, search_text, git_diff
---

You review code changes. Report concrete bugs with file and line, and
missing tests. Don't comment on style.
```

## Isolated worktrees

A sub-agent can work in its own Git worktree, so several agents edit the same repository without colliding. The worktree is created under `~/.kazocode/worktrees/` on a new branch named `kazo/<agent id>`. When the agent finishes without changes, the worktree and branch are removed; otherwise the result says where they are and how to merge them.

## Agent Workspace

The Agent Workspace (`Ctrl+Alt+A`) runs one agent per task, side by side in lanes. Pick a repository, describe the task, and each agent works in its own worktree by default. For each lane you can follow progress, send a follow-up, stop it, open the changed files as diffs, and **Merge** the work when it's ready.

## Workflows

`/workflow` runs multi-agent workflows: an audit, a migration, a port, a test pass, a security review, or one you define in `.kazo/workflows/`. A workflow splits the work across agents, tracks each step, and can be watched, resumed or cancelled.
