Feature Request: Background Process → Claude Code Communication Channel

Summary

Add a mechanism for background processes spawned by Claude Code to signal events (like readiness) back to Claude Code, eliminating the need for polling-based health checks.

Current Behavior

When Claude Code spawns a long-running process in the background (e.g., a dev server), the only way to know when it's ready is to:

1. Sleep for an arbitrary duration
2. Poll an HTTP endpoint repeatedly
3. Tail the output file looking for specific log patterns

This leads to inefficient patterns like:

# Start webapp in background
pnpm run dev --filter webapp  # run_in_background: true

# Then Claude Code does something like:
sleep 60 && curl http://localhost:3030/healthcheck

Problem

• Wasted time: Fixed sleep durations are either too short (process not ready) or too long (unnecessary waiting)
• Unreliable: Polling can miss the ready state or waste cycles
• No structured communication: Output file parsing is fragile and ad-hoc

Proposed Solution

Inject environment variables into background processes that enable structured communication back to Claude Code:

CLAUDE_CODE_TASK_ID=task_abc123
CLAUDE_CODE_IPC_PATH=/tmp/claude-code-ipc-abc123.sock
# or
CLAUDE_CODE_CALLBACK_PORT=52847

Processes could then signal events:

// In the spawned process (e.g., webapp startup)
if (process.env.CLAUDE_CODE_IPC_PATH) {
  const socket = net.connect(process.env.CLAUDE_CODE_IPC_PATH);
  socket.write(JSON.stringify({ 
    event: "ready", 
    message: "Server listening on port 3030" 
  }));
}

Or via a simple HTTP callback:

if (process.env.CLAUDE_CODE_CALLBACK_PORT) {
  fetch(`http://localhost:${process.env.CLAUDE_CODE_CALLBACK_PORT}/event`, {
    method: "POST",
    body: JSON.stringify({ event: "ready", port: 3030 })
  });
}

Claude Code Side

Add a tool or parameter to wait for process signals:

TaskOutput(task_id: "...", wait_for_event: "ready", timeout: 30000)

This would block until the process signals "ready" or timeout occurs.

Use Cases

1. Dev servers: Wait for webpack/vite/remix to finish compilation and start listening
2. Database migrations: Know when migrations complete before running seeds
3. Build processes: Signal when build artifacts are ready
4. Test runners: Stream test results back in real-time
5. Any long-running process: Replace arbitrary sleeps with deterministic signaling

Alternative: Simpler Approach

If full IPC is too complex, even a simple file-based protocol would help:

CLAUDE_CODE_SIGNAL_FILE=/tmp/claude-code-task-abc123.signal

Process writes to the file, Claude Code watches it:

echo '{"event":"ready"}' > $CLAUDE_CODE_SIGNAL_FILE

Impact

This would significantly improve the reliability and efficiency of Claude Code workflows that involve background processes, which is increasingly common for local development and testing scenarios.