claude-memory/graph/code-patterns/command-background-agent-pattern-for-context-dependent-async-9369e5.md

id	type	title	tags	importance	confidence	created	updated
9369e53e-123c-4102-b69d-2a4705f2388e	code_pattern	Command + background agent pattern for context-dependent async work	claude-code commands agents pattern architecture	0.6	0.8	2026-02-19T22:09:59.147931+00:00	2026-02-19T22:09:59.147931+00:00

Pattern for tasks needing conversation context but should run asynchronously.

Pattern Structure

1. Slash command in .claude/commands/ runs inline with full conversation context
2. Command analyzes context and builds structured summary
3. Command spawns custom agent from .claude/agents/ in background via Task tool with run_in_background=true
4. Agent receives summary as prompt and does heavy lifting
5. User gets control back immediately

Workflow

• Command has access to full conversation history → ideal for context analysis
• Agent runs asynchronously → ideal for time-consuming operations
• Structured summary bridges the two → cleanly separates concerns

Real-World Example

/save-memories command:

• Command analyzes conversation, finds duplicate cutoff, builds memory summary
• Spawns memory-saver agent with summary
• User can continue working while agent stores items

Implementation Notes

• Newly created agents require a session restart to appear in the subagent_type list
• Until then, use subagent_type: general-purpose as fallback
• Agent receives summary via prompt, not conversation history
• Task tool with run_in_background=true prevents blocking user

Applicable To

Any task that:

• Requires analyzing session/conversation context
• Takes time to execute (network, storage, processing)
• Should not block the user
• Needs to defer execution to another agent