version: "1.0.1" name: worker-agents description: "You have a task that would benefit from running in a separate isolated Claude Code session — either because it is long-running and you do not want it to consume your context window, or because you want multiple pieces of work running in parallel that each require a full Claude Code session with its own tools, memory, and context (not just a subagent call). You will spawn one or more ephemeral worker sessions, give each a focused task, monitor their progress via the bus, and collect their outputs when done." triggers: ["worker", "parallelize", "spawn worker", "spin up", "parallel work", "background task", "isolated session", "separate session", "long running task", "run in background", "parallel research", "multiple workers", "worker session", "spawn session", "full claude code session", "context window", "parallel tasks", "run simultaneously", "independent sessions"]

Worker Agents

Spawn ephemeral Claude Code sessions for parallelized long-running tasks. Workers get a scoped task, produce deliverables, and are cleaned up when done. Use when work requires a full independent Claude Code session — not just a subagent tool call.

Worker session spawn is fully implemented. Use cortextos spawn-worker to launch isolated Claude Code sessions for parallelized tasks.

When to Use

Good fit:

• Independent work that does not touch files another agent is editing
• Research or design docs in a new directory
• Scaffolding a new feature in isolation
• Any task > 5 minutes that can run while you do other work

Bad fit:

• Editing files another agent or worker is actively touching (merge conflicts)
• Tasks needing real-time back-and-forth (just do it yourself)
• Very short tasks < 2 minutes (overhead not worth it)

How Workers Differ from Persistent Agents

Workflow (Concepts — Implementation TBD)

Step 1: Scope the Work

Before spawning, answer:

1. What specific deliverables should the worker produce?
2. Which files/directories will it create or modify?
3. Does this overlap with any active agent or worker? If yes, do NOT parallelize.
4. What context does the worker need?

Step 2: Spawn Worker Session

cortextos spawn-worker <worker-name> \
  --dir <absolute-path-to-project-dir> \
  --prompt "Read AGENTS.md for your task. Deliverables: <list>. When done: cortextos bus send-message $CTX_AGENT_NAME normal 'Done: <summary>'" \
  --parent $CTX_AGENT_NAME

The worker:

• Runs claude --dangerously-skip-permissions in the given directory
• Gets a bus identity (CTX_AGENT_NAME=<worker-name>) for two-way communication
• Logs to ~/.cortextos/<instance>/logs/<worker-name>/stdout.log
• Is tracked by the daemon — use cortextos list-workers to monitor status

Step 3: Inject Task Prompt

A good worker task prompt includes:

• Exact deliverables (specific files or outputs to produce)
• What NOT to touch (files other agents own)
• Working directory scope
• How to communicate back (cortextos bus send-message <parent> normal '<update>')
• Completion signal ("when done, send me a summary")

Step 4: Log the Spawn

cortextos bus log-event action worker_spawned info \
  --meta '{"worker":"<worker-name>","parent":"'$CTX_AGENT_NAME'","task":"<title>"}'

Step 5: Monitor

Workers communicate back via the bus. Check your inbox:

cortextos bus check-inbox

Check all worker statuses:

cortextos list-workers
# Output: worker-name  running (pid 12345) ← parent-agent  42s  /path/to/dir

Check git progress in the worker's directory:

cd <work-dir> && git log --oneline | head -5

Nudge a stuck worker (equivalent of tmux send-keys):

cortextos inject-worker <worker-name> "Continue with phase 3. What's blocking you?"

Step 6: Cleanup

# Terminate a running worker
cortextos terminate-worker <worker-name>
 
# Log completion
cortextos bus log-event action worker_completed info \
  --meta '{"worker":"<worker-name>","deliverables":"<summary>"}'

Scaling Rules

Hard rules:

• NEVER spawn workers for overlapping file sets
• NEVER let workers modify files you or other agents are editing
• ALWAYS log spawns and completions
• Workers should NOT spawn their own workers (no worker-ception)