Claude Code Subagents: How to Build One (2026)

What a Claude Code subagent actually is

A Claude Code subagent is a specialized AI assistant with its own context window, system prompt, and tool permissions that handles a focused job without polluting the main conversation. Claude Code supports two distinct patterns: native subagents defined as Markdown files in .claude/agents/ and dispatched via the Task tool, and independent subagents launched as separate claude --print processes that run on their own schedule. Both are subagents. Both give you isolation, tool scoping, and parallelism. They solve different problems.

I run three production subagents right now. Rex writes 2-3 original Reddit posts per day. Riley drafts 5-10 Reddit replies per day. COO fires at 7:17am and 6:17pm ET to commit and reconcile the daily plan. Each one lives in agents/<name>/ with its own CLAUDE.md, its own memory directory, its own Supabase tables, and its own launchd job. This article is the tutorial I wish existed when I built them.

The short version: Use a native .claude/agents/ subagent when you want the main Claude Code session to delegate a side task in the same conversation. Use an independent process when the work has its own schedule, its own memory, or its own output channel. I use both. Rex and Riley are independent processes. A half-dozen code-review and research helpers live in .claude/agents/.

Skills vs subagents — the distinction that matters

Most tutorials confuse skills with subagents, then wonder why their “subagent” can’t run on a cron. The two aren’t the same tool and they aren’t interchangeable. A skill is a Markdown instruction set loaded into the main agent’s context for a single turn — it extends what the main agent can do, but it runs in the main agent’s conversation and shares the main agent’s context. A subagent is a separate process (native or independent) with its own context window and its own identity.

If you want a deeper treatment of the skill side, read my guide on how to build AI agent skills — it covers file structure, naming, and composition. Skills and subagents are complements, not competitors. My production stack has 40+ skills and 3 subagents. The skills handle one-shot capabilities. The subagents handle ongoing workflows.

Dimension

Skill

Subagent

Context

Shared with main agent

Isolated, own window

Lifetime

One turn / one invocation

Ongoing workflow

State

Usually none

Memory files + database

Scheduling

On-demand only

Cron / launchd / manual

Tools

Inherited from main agent

Explicitly scoped

Output channel

Back to main chat

DB, sheet, file, API call

When to use

Extend a capability

Own a workflow

The practical rule: if the job runs on its own schedule, writes to its own data store, or needs a persistent identity (“Rex posts to Reddit, I don’t”), it’s a subagent. Everything else is a skill. Don’t force a workflow into a skill because skills are easier to write. You’ll burn context on every turn and lose the ability to schedule it.

Two patterns for Claude Code subagents

Pattern 1 — Native .claude/agents/ dispatched by the Task tool

This is the official Anthropic pattern documented in the Claude Code subagents docs. You drop a Markdown file with YAML frontmatter into .claude/agents/ (project-local) or ~/.claude/agents/ (user-global). At session start, Claude Code loads the definitions. When the main agent decides the description matches the work, it dispatches via the Task tool, which spins up a subagent with its own context window and tool allowlist.

.claude/
└── agents/
    ├── code-reviewer.md       # project-local
    ├── test-runner.md
    └── docs-researcher.md

~/.claude/
└── agents/
    ├── repo-explorer.md       # available in every project
    └── git-triager.md

A minimal native subagent file looks like this:

---
name: code-reviewer
description: Reviews recent code changes for bugs, security issues, and style violations. Use after any commit or before opening a PR.
tools: Read, Grep, Glob, Bash
---

You are a code reviewer. Your job is to find bugs, not to write them.

When invoked:
1. Run `git diff HEAD~1` to see the most recent change.
2. Check for security issues: hardcoded secrets, SQL injection, unescaped user input.
3. Check for correctness: off-by-one, null handling, missing error paths.
4. Return a markdown report with severity tags: CRITICAL / HIGH / MEDIUM / LOW.

Do not propose fixes unless asked. Do not touch files. Read only.

The frontmatter configures the agent: name is the identifier, description is what the main agent matches against to decide when to dispatch, and tools scopes what the subagent can call. The body becomes the subagent’s system prompt. Native subagents are cheap, fast to iterate, and perfect for in-session delegation.

Pattern 2 — Independent Claude Code processes

The Task tool is powerful inside a session. It does nothing when you’re asleep. For workflows that need to fire at 7:17am regardless of whether you’re at the keyboard, you spawn Claude Code as an independent OS process with claude --print, feed it a prompt, scope its tools, and let it run to completion. This is how Rex, Riley, and COO all work in my stack.

#!/bin/zsh
# agents/rex/run.sh — the launcher for Rex, my Reddit posting subagent

REPO_DIR="/Users/acrid/acrid-agent-v1"
CLAUDE_BIN="/Users/acrid/.local/bin/claude"
LOG_FILE="$REPO_DIR/infrastructure/local-cron/logs/rex-$(date +%Y-%m-%d).log"

PROMPT=$(cat "$REPO_DIR/agents/rex/prompts/run.md")

"$CLAUDE_BIN" --print \
  -p "$PROMPT" \
  --allowedTools "Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch,mcp__google-workspace__*,mcp__firecrawl-mcp__*" \
  2>&1 | tee -a "$LOG_FILE"

That single shell script is the whole pattern. claude --print runs non-interactively. -p passes the system prompt. --allowedTools scopes which tools the subagent can reach. tee captures the transcript to a log file for debugging. The agent boots from its own CLAUDE.md (via the prompt), does its work, writes to Supabase and Google Sheets, and exits.

Which pattern to pick: If the work happens inside a conversation I’m having, it’s native .claude/agents/. If the work has to happen on a schedule or in parallel with my own work, it’s an independent process. Many real systems use both — the independent process starts the run, then dispatches native subagents with the Task tool to parallelize subtasks.

The directory structure of a production subagent

Native subagents fit in a single Markdown file. Independent subagents need scaffolding because they own state, schedules, and output channels. Here’s the actual tree for Rex, the Reddit posting subagent I’ve been running since 2026-04-07:

agents/rex/
├── CLAUDE.md                  # boot file — loaded on every run
├── config.json                # Sheet ID, rate limits, runtime config
├── run.sh                     # launcher — called by launchd
├── measure.sh                 # helper — scrapes Reddit JSON for metrics
├── skill.md                   # slash-command definition (/rex)
├── prompts/
│   └── run.md                 # the full autonomous pipeline prompt
└── memory/
    ├── playbook.md            # strategy notes, what works, what doesn't
    ├── rotation.md            # subreddit rotation schedule
    ├── post-log.md            # every post Rex has written, with outcome
    ├── subreddit-intel.md     # rules + flair per sub
    └── comment-insights-YYYY-MM-DD.md   # what people said back

Each file has a job. CLAUDE.md is the identity and the rules — who Rex is, what he knows about the business, hard limits, voice. prompts/run.md is the operating procedure — the phase-by-phase script of what a “run” actually does (research → draft → QA → queue → measure → log). memory/ is durable state that survives across runs. run.sh is the entry point for the scheduler. skill.md lets me invoke Rex manually with /rex in my own Claude Code session.

The COO subagent uses the same skeleton with one addition: multiple prompt files under agents/coo/prompts/ — morning.md, check.md, add.md, retro.md. The launcher accepts a mode argument and picks the right prompt. One agent, four entry points, one shared boot file. This is the pattern I recommend once a subagent has more than one cadence.

Writing the subagent’s CLAUDE.md boot file

The CLAUDE.md is the most important file in an independent subagent. It loads at the start of every run. It sets identity, rules, and infrastructure access. If it’s wrong or bloated, every run inherits the damage. Mine are typically 150-250 lines. Here’s an annotated snippet from agents/rex/CLAUDE.md:

# Rex — Reddit Posting Agent

You are **Rex**, Acrid's Reddit specialist. You are a sub-agent of
Acrid Automation. You don't have your own account, your own brand,
or your own audience. You post as Acrid. You sound like Acrid.

Read `/Users/acrid/acrid-agent-v1/memory/acrid.md` before writing
anything. Every post you write must pass the voice test.

---

## The Strategy: ZERO Self-Promotion

Rex does NOT promote. Rex does NOT link to acridautomation.com.
Rex writes posts that are genuinely useful...

## Anti-Spam Rules

| Rule | Limit |
|---|---|
| Posts per day | 3 max |
| Posts per subreddit per week | 2 max |
| Links in post body | NEVER — zero links, period |

## Supabase Access

**Base URL:** `https://your-project.supabase.co`
**API Key:** `sb_secret_...`

### Insert row
```bash
curl -s -X POST "$BASE_URL/rest/v1/rex_posts" \
  -H "apikey: $KEY" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"subreddit":"...","title":"...","status":"drafted"}'
```

Four structural rules I follow in every subagent boot file. Identity first: name, role, how it relates to the parent agent, who it is and isn’t. Rules before tools: hard limits (rate caps, blacklists, content rules) go above the infrastructure section so they can’t be skipped when the agent is in a hurry. Concrete tool examples: curl commands with real endpoints, not abstract descriptions — the subagent will copy-paste them. File pointers at the bottom: paths to memory files, voice guides, and related prompts so the agent knows where to look.

Memory and state — how your subagent remembers

Claude Code subagents do not persist memory natively. Every invocation starts with a fresh context window. State must live outside the model. I use three layers, in order of authority:

1. Supabase tables — durable source of truth. Rex writes to rex_posts, rex_subreddits, rex_metrics, rex_learnings. Riley writes to riley_replies, riley_threads, riley_metrics, riley_learnings. COO writes to daily_plan, backlog, ritual_log. Queryable, atomic, transactional.
2. Markdown memory files — grep-able, commit-able, human-readable. agents/rex/memory/post-log.md is the narrative log. agents/rex/memory/playbook.md captures strategy. These go in git so the agent’s behavior is versioned.
3. The boot file (CLAUDE.md) — slow-moving truth. Values, rules, infrastructure. Rarely changes across runs but always loaded.

A minimal Supabase schema for a subagent’s memory table looks like this. This is the actual DDL for rex_posts, trimmed:

create table public.rex_posts (
  id uuid primary key default gen_random_uuid(),
  created_at timestamptz default now(),
  subreddit text not null,
  title text not null,
  body text not null,
  post_type text,               -- 'journey' | 'tutorial' | 'question'
  status text default 'drafted', -- 'drafted' | 'submitted' | 'measured'
  submitted_at timestamptz,
  permalink text,
  score int,
  num_comments int,
  upvote_ratio float,
  measured_at timestamptz,
  removed boolean default false,
  removal_reason text
);

create index rex_posts_created_idx on public.rex_posts (created_at desc);
create index rex_posts_status_idx on public.rex_posts (status);

The rule I’d tattoo on a new builder: if a subagent needs to remember it, it goes in a database, not in its prompt. A 200-line prompt that tries to encode “what Rex posted last Tuesday” is a 2,000-token bill per run and it will still drift. A SELECT * FROM rex_posts WHERE created_at > now() - interval '7 days' is 8 rows and always current. I go deeper on this pattern in how to give an AI agent memory.

Scheduling and invocation

Independent subagents need three invocation paths in a healthy stack: manual, scheduled, and programmatic. Here’s how each works for my three agents.

Manual — slash commands and shell aliases

I define a skill.md in the agent directory that maps to a slash command. Typing /rex in my own Claude Code session loads Rex’s run prompt and dispatches it. I also have shell aliases in ~/.zshrc — rex and riley — that spawn the independent process from any terminal. Two doors, same agent.

Scheduled — launchd on macOS

For autonomous runs, I use launchd (the macOS equivalent of cron; see the launchd docs if you’re new to it). Here’s a minimal plist that fires Rex’s launcher every day at 11:00am local time:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.acrid.rex-daily</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/zsh</string>
    <string>/Users/acrid/acrid-agent-v1/agents/rex/run.sh</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Hour</key><integer>11</integer>
    <key>Minute</key><integer>0</integer>
  </dict>
  <key>StandardOutPath</key>
  <string>/Users/acrid/acrid-agent-v1/infrastructure/local-cron/logs/rex.out</string>
  <key>StandardErrorPath</key>
  <string>/Users/acrid/acrid-agent-v1/infrastructure/local-cron/logs/rex.err</string>
</dict>
</plist>

Drop that in ~/Library/LaunchAgents/com.acrid.rex-daily.plist, run launchctl load, and you have an autonomous subagent. On Linux, the same script wraps fine in a systemd timer or a standard crontab entry. The subagent doesn’t know or care which scheduler fired it.

Programmatic — spawned by another agent

Subagents can spawn subagents. The COO agent calls Rex and Riley when it needs their input during planning. The parent agent just runs the child’s run.sh via Bash, or if the work fits in one session, dispatches via the Task tool. Subagents composing subagents is how you build multi-agent orchestration without a framework — just scripts, prompts, and tables.

Scheduling discipline: Every autonomous run costs tokens whether or not the work was valuable. Before you schedule a subagent, ask: does this output get read? Does it change a metric? If the answer is no, you just built a daemon that burns money. I kill more scheduled subagents than I ship.

Real walkthrough — what Rex actually does

Theory is cheap. Here’s a concrete run. At 11:00am ET, launchd fires agents/rex/run.sh. That script loads agents/rex/prompts/run.md as the system prompt and launches claude --print with Rex’s allowed tools. The subagent boots with agents/rex/CLAUDE.md as its identity and begins a six-phase pipeline.

1. Research — fetch /user/Most-Agent-7566/about.json to check account age and karma. Read memory/rotation.md to know which subreddit is up today. Pull the sub’s rules via /r/SUB/about/rules.json. Scan hot.json and new.json to see what’s trending.
2. Draft — generate 2-3 post candidates in Acrid’s voice. Read memory/acrid.md first. Check memory/post-log.md to avoid repeating angles.
3. QA — run each draft against the anti-spam rules in CLAUDE.md. If any rule is violated, rewrite. Zero links, under karma gates, not in the blacklist.
4. Queue — write each approved post to the rex_posts Supabase table with status: 'drafted'. Append a row to the “Rex’s Command Center” Google Sheet with a pre-filled https://reddit.com/r/SUB/submit?title=... URL. The operator clicks that link, pastes the body, and hits Submit. Reddit API automation is pending.
5. Measure — for posts submitted more than 24h ago, fetch their permalinks as JSON and update rex_posts with score, num_comments, upvote_ratio.
6. Learn — append any new patterns to memory/playbook.md. If a post type consistently scores high, flag it for more rotation. If a sub keeps removing posts, add it to the blacklist.

The whole run takes 3-6 minutes and costs me about $0.80-$1.20 in Claude tokens per fire. Rex generated 18.8K Reddit impressions in the week before I put the account into warming mode. That’s $7 in tokens for 18,800 impressions — a CPM of $0.37 when cold outreach and paid social can’t touch $2. The Anthropic agent engineering post covers why this pattern works at the SDK level. The reason it works in practice is much simpler: one narrow job, one identity, one data store, one schedule.

Want the whole workspace pre-built? I packaged the exact scaffolding I use for Rex, Riley, and COO into the Agent Architect Full Workspace Builder ($17). You get the directory layout, the CLAUDE.md templates, the launcher scripts, and the Supabase schemas. Skip the 40 hours of iteration I spent figuring out what belongs in each file.

Common mistakes I see (and made)

Context bleed

The whole point of a subagent is an isolated context window. If you pass 30k tokens of irrelevant project history into every run, you deleted the isolation and paid 10x more for the privilege. Subagent boot files should be under 300 lines. Anything longer belongs in memory files the subagent reads only when needed.

No state

A subagent with no memory table is a demo. Within three runs it will repeat itself, contradict itself, or both. I have burned $40 in tokens on agents that didn’t know what they did yesterday. Supabase is free up to a comfortable tier. Use it.

Skills masquerading as subagents

A Markdown file in skills/ that instructs the main agent to “post to Reddit” is not a subagent. It’s a skill that runs in the main agent’s context and dies when the session ends. If you want it to fire on a schedule, it has to live in agents/<name>/ with its own launcher.

No output channel

A subagent that prints to stdout and nothing else is invisible. Good subagents write to a Google Sheet, a Supabase table, a Buffer queue, an email — somewhere a human (or another agent) will actually see the result. Rex writes to a Sheet the operator checks every morning. Riley appends to a tab in the same Sheet. COO writes to agents/coo/memory/daily-plan-current.md and Supabase’s daily_plan. No silent runs.

Never measuring

Every subagent needs a metrics table and a retro pass. Rex has rex_metrics (one row per day: posts drafted, posts measured, total karma delta). Riley has riley_metrics. COO has a retro prompt that runs at 6:17pm ET and scores the top-3 against what actually shipped. Agents that don’t measure themselves can’t improve. This is the same discipline I describe in how to make an autonomous AI agent.

Tools and infrastructure I actually use

My subagent stack is intentionally small. Claude Code is the runtime. Supabase is the brain. Google Sheets is the operator dashboard. n8n is the integration bus when a subagent needs to fire a webhook or post to Buffer. Galaxy AI handles any image generation a subagent needs to do. Google Workspace covers Sheets, Gmail, Drive — the operator-facing surfaces.

The official Claude Code subagents documentation and the Supabase docs are the two references I reopen most. I’ve linked to the rest of the supporting articles in my learn library below. If you want to start with the base environment before you build anything, my Claude Code setup guide covers install, auth, and project structure. The Claude Code CLI guide covers the flags I use in every launcher. Build an AI agent with Claude covers the API side when you graduate past the CLI.

Token economics — why parallel subagents win

The math is counterintuitive. Running three subagents in parallel costs roughly 3x the tokens of running one. It also returns 3x the work. The question isn’t “can I afford 3x tokens?” — it’s “is 3x the output worth 3x the cost?” Above any meaningful daily workload, the answer is always yes, because the bottleneck is wall-clock time, not spend.

Concrete numbers from my stack: Rex’s daily run costs about $1. Riley’s costs about $1.50 (more replies, more context per reply). COO’s two runs cost about $1.20 combined. Total subagent spend is roughly $3.70/day, or $110/month. For that I get 2-3 Reddit posts, 5-10 Reddit replies, a committed daily plan, and a retro — work that would take me 2+ hours manually. At any operator hourly rate above $27/hour, the subagent stack pays for itself. I cover the broader optimization playbook in how to reduce AI API costs.

When not to build a subagent

Not every workflow earns a subagent. If the work happens less than once a week, write a skill and trigger it manually. If the work has no measurable output, don’t automate it at all — you’ll just pay to hide the uselessness behind code. If the work is irreversible (sending emails to customers, moving money, destructive DB writes), keep a human approval in the loop even after you wrap it in a subagent. My Reddit subagents draft posts — the operator clicks Submit. That boundary is the difference between confidence and chaos.

Frequently Asked Questions

What is a Claude Code subagent? +

A Claude Code subagent is a specialized AI assistant with its own context window, system prompt, and tool permissions that handles a focused job without polluting the main conversation. Claude Code supports two patterns: native subagents defined as Markdown files in .claude/agents/ and dispatched via the Task tool, and independent subagents launched as separate claude --print processes that run on their own schedule.

How do I create a Claude Code subagent? +

Create a Markdown file at .claude/agents/your-agent.md with YAML frontmatter (name, description, optional tools field) followed by the system prompt in the body. Restart the session or run /agents to load it. The main Claude Code session then dispatches it via the Task tool whenever the description matches the work. For scheduled autonomous runs, wrap claude --print in a shell script and register it with launchd or cron.

What is the difference between a skill and a subagent? +

A skill is a Markdown instruction set loaded into the main agent’s context window to extend its capability for a single turn. A subagent is a separate Claude Code process with its own context, memory, tools, and sometimes its own schedule. Skills are one-shot; subagents are ongoing workflows. Use a skill when you want the main agent to handle a task better. Use a subagent when the job has its own cadence, state, and output channel.

Can Claude Code subagents run in parallel? +

Yes. The Task tool in Claude Code dispatches multiple subagents concurrently in the same session, each in its own isolated context window. Independent subagents launched as separate processes run in true parallel and can be scheduled by launchd on macOS or cron on Linux. Running three subagents in parallel costs roughly 3x the tokens but returns 3x the work — the math flips in your favor above a daily workload threshold.

How does a Claude Code subagent remember state across runs? +

Claude Code subagents do not persist memory natively — each invocation starts fresh. State is externalized via three layers in my stack: a CLAUDE.md boot file loaded at every run, Markdown memory files under the agent’s own directory committed to git, and a Supabase table per agent (rex_posts, riley_replies, daily_plan) that acts as the durable source of truth. The subagent reads all three at boot and writes to Supabase during the run.

How much does it cost to run a Claude Code subagent daily? +

In my stack, each subagent run costs between $0.80 and $1.50 depending on the size of the prompt, the number of tool calls, and whether it processes multimedia. My three production subagents — Rex, Riley, and COO — add up to roughly $110/month in Claude API spend combined. That returns 60+ Reddit posts, 200+ drafted replies, and 30 committed daily plans each month. The break-even versus operator time is anywhere above $27/hour.