Three State-Passing Patterns for Claude Code Subagents — Lessons from 4 Months of Automated Blog Pipelines

Pattern 2: Environment variables (best for small, fast references)

The next pattern keeps only a short identifier in an environment variable; the actual state lives in a KV store. This combines well with Cloudflare Workers KV.

Implementation

# Parent: put the state in KV; pass only the ID via env
PIPELINE_ID="run-$(date +%s)-${RANDOM}"
wrangler kv key put --binding=PIPELINE_STATE \
  "${PIPELINE_ID}" "$(cat current_state.json)" \
  --remote
 
# Child reads the ID from the env, then fetches from KV
export CLAUDE_PIPELINE_ID="${PIPELINE_ID}"
claude-code -p "$(cat <<EOF
Read CLAUDE_PIPELINE_ID from the environment and pull state from:
  https://internal.example.com/state/\${CLAUDE_PIPELINE_ID}
EOF
)"

The 32KB trap

My first instinct was the lazy version: serialize the entire state into an env var and skip file I/O altogether. Overhead clocked in at 0.3ms — practically free.

In production, however, the moment state hit roughly 32KB, child processes started crashing on launch. Linux's ARG_MAX puts a practical ceiling on the combined size of argv and the environment (around 128KB depending on the distribution); cross it and the child dies with E2BIG. If state might grow, keep only the ID in the env and fetch the body from a real store.

When to choose this

This shines for small, fast lookups — a user ID, a run ID, a cache-version counter. I use it to pass a GSC-data cache generation number so the child can quickly decide whether to refresh.

Pattern 3: Context Bundle (best for long-running pipelines over 1,000 runs)

The third pattern formats state as a readable Markdown "Context Bundle" and inlines it into every subagent prompt. It mirrors how Anthropic's own Skills system attaches reference documents wholesale.

Implementation

function buildContextBundle(state: PipelineState): string {
  return `
# Pipeline Context (generated: ${new Date(state.timestamp).toISOString()})
 
## Recent slugs (avoid duplicates)
${state.recentSlugs.map(s => `- ${s}`).join('\n')}
 
## Article count by category (rebalance target)
${Object.entries(state.categoryBalance)
  .sort((a, b) => b[1] - a[1])
  .map(([cat, count]) => `- ${cat}: ${count}`)
  .join('\n')}
 
## Top GSC performers (last 10)
${Object.entries(state.gscData)
  .sort((a, b) => b[1].clicks - a[1].clicks)
  .slice(0, 10)
  .map(([slug, data]) => `- /${slug}: ${data.clicks} clicks, CTR ${(data.clicks/data.impressions*100).toFixed(1)}%`)
  .join('\n')}
 
## Exclusion list (cross-site)
${state.excludedSlugs.slice(0, 50).map(s => `- ${s}`).join('\n')}
${state.excludedSlugs.length > 50 ? `\n(${state.excludedSlugs.length - 50} more omitted)` : ''}
`;
}
 
const childPrompt = `
${buildContextBundle(state)}
 
---
 
Using the context above, pick a topic for a new premium article and draft it.
`;

Expensive, but it buys reasoning quality

Measured overhead is 380ms, and token consumption runs about 3x higher than the JSON pattern. The reason to pay that cost is that the child doesn't need to perform any "go fetch the state" step. No Read call, no network I/O — from the very first second of inference, the child can focus on topic selection.

I reserve this for weekly retrospective articles. Those need to look across an entire week's worth of metadata at once. The runs are infrequent enough that I'd rather spend tokens than risk a child agent reasoning over partial information.

Watch for token blowup

One month I forgot to bound the bundle size for a monthly retrospective and a single subagent invocation burned 45,000 tokens. In production I now guard every bundle:

const MAX_BUNDLE_TOKENS = 8000; // rough rule: 1 token ~ 4 chars
const MAX_BUNDLE_CHARS = MAX_BUNDLE_TOKENS * 4;
 
function buildContextBundleSafe(state: PipelineState): string {
  const bundle = buildContextBundle(state);
  if (bundle.length > MAX_BUNDLE_CHARS) {
    // Trim oldest slugs first
    const trimmed = {
      ...state,
      recentSlugs: state.recentSlugs.slice(0, 30),
      excludedSlugs: state.excludedSlugs.slice(0, 20),
    };
    return buildContextBundle(trimmed);
  }
  return bundle;
}

The three patterns at a glance

Numbers below are from real production runs, not synthetic benchmarks.

• JSON file — Overhead 12ms / Best scale: up to 100 runs per day / Watch out for concurrent writers / Cost: parent-side I/O only
• Env vars — Overhead 0.3ms / Best scale: tiny payloads (IDs and flags) / Watch out for the ~32KB ARG_MAX ceiling / Cost: essentially zero
• Context Bundle — Overhead 380ms / Best scale: 1,000+ runs over long horizons / Watch out for token blowup / Cost: roughly 3x token usage

How I actually choose

When I design a new pipeline I walk through this decision in order:

1. If the state is under 1KB and it's basically "an ID plus a few flags," I reach straight for env vars
2. If the state is 1KB to 100KB and parallelism stays at four or below, I go with JSON files
3. If the state crosses 100KB, or the child needs to reason over the state from the first token, I use a Context Bundle

When pipelines grow I hybridize. The daily pipeline stays on JSON files; the monthly aggregation switches to Context Bundles. The boundary is the value of the child's first second of thought.

Three lessons that stuck

I'll close with three notes I wrote down in my own logbook.

The first lesson is to never commit to one pattern up front. Whether Cowork's scheduler will overlap your runs, and how quickly state will grow, are things you only learn from running the pipeline. A thin abstraction that lets you swap between the three patterns is cheap insurance against breaking changes later.

The second lesson is to always pair persistence with TTL. Early on I put JSON files in /tmp and forgot about expiration; whenever the sandbox VM restarted the state vanished and I generated duplicate articles before noticing. If the state needs to outlive a VM, use a Dropbox-synced directory or a KV store.

The third lesson is that the best subagent design is the one where the child never needs to read state at all. My main app business has long passed the point where automation is uncontroversial, but I still find that polishing what the child "thinks in the first second" is the highest-leverage place to spend time.

If you're designing something similar, I hope this saves you a few months. Thanks for reading.