[FEATURE] Native agent scheduling / daemon mode (watch + wake)

Problem Statement

Claude Code sessions are ephemeral -- when a session ends, all background work dies. There is no native way to:

• Run an agent on a schedule ("check this resource every 5 minutes")
• Keep an agent alive between sessions (daemon mode for long-running tasks)
• Watch a resource and wake an agent when it changes (event-driven response)
• Fire-and-forget a long-running task that outlives the session (async work)
• Schedule a follow-up session ("run this prompt again in N minutes")

This means any workflow requiring periodic monitoring, event-driven response, or long-running background work must be built entirely outside the harness.

Concrete impacts

• Monitoring external resources (issue trackers, CI pipelines, message queues) requires custom infrastructure outside Claude Code
• Event-driven workflows (react when a collaborator comments, respond when a build fails) need custom polling + wake systems
• Long orchestration chains that outlive a single session have no continuation mechanism
• Multi-agent coordination across sessions requires building your own scheduling, state deduplication, and session invocation layer

Proposed Solution

Any combination of these primitives would dramatically reduce the infrastructure burden:

1. Agent scheduling primitive: "run this prompt every N minutes" -- a built-in cron-like capability tied to agent definitions. Could be as simple as a schedule field in agent frontmatter.

1. Resource watch: "wake me when this file/URL/endpoint changes" -- register a watch on a resource, and the system creates a new session with context when it detects a change.

1. Event-driven wake: "when a message arrives at this endpoint, start a session with this context" -- the existing /api/wake endpoint concept but with native scheduling support and context injection.

1. Daemon mode: "keep this agent alive, processing a queue" -- a long-lived agent process that sleeps between events rather than terminating after each response.

1. Post-session continuation (minimum viable version): "when this session ends, schedule a follow-up in N minutes with this context" -- the simplest possible primitive that would still eliminate most of the custom infrastructure.

How it might look

# .claude/agents/monitor.md frontmatter
---
schedule: "*/5 * * * *"          # every 5 minutes
watch:
  - path: ".github/issues"       # or a URL, or an API endpoint
trigger: "on_change"              # or "on_schedule", "on_message"
context: "Check for new activity and respond"
---

Or as a CLI primitive:

# Schedule a recurring agent run
claude agent schedule monitor --every 5m --context "Check for updates"

# Watch a resource
claude agent watch --url "https://api.github.com/repos/org/repo/issues" --on-change "Triage new issues"

# Post-session continuation
claude agent continue --in 10m --context "Follow up on the deployment"

Alternative Solutions

What we built to work around it

We constructed a full scheduling and wake infrastructure outside Claude Code:

1. Cron-based polling: A Python script runs every 5 minutes via system cron, checks GitHub for activity using gh api, with fcntl lockfile to prevent overlapping runs and a state file with TTL pruning to prevent re-processing.

1. Swarm messaging layer: When the cron script detects activity, it sends a structured message to a message queue via CLI. The message includes context about what changed.

1. Wake system: Message delivery triggers a tmux-based session invocation that launches a new Claude Code session with the wake context. Two separate asyncio.create_subprocess_exec calls with a sleep between them (because tmux send-keys drops the Enter key if text and C-m are sent in one call).

1. State deduplication: The polling script maintains state to avoid re-processing the same events. TTL-based pruning prevents the state file from growing unbounded.

1. End-to-end flow: cron -> Python script -> message send -> HTTP delivery -> tmux session -> Claude Code wake -> orchestrator processes -> session terminates

This is hundreds of lines of infrastructure code, multiple system-level components (cron, tmux, systemd, FastAPI server), and a full messaging protocol -- all to achieve "check GitHub and react." Every team running multi-agent Claude Code systems likely builds some variant of this.

Other tools considered

• Raw tmux scripting for session management (fragile, no scheduling)
• systemd timers calling claude CLI directly (works but no context injection or state management)
• File-watching with inotifywait + hook scripts (only covers local filesystem, not remote resources)

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK

Use Case Example

Scenario: Multi-agent team monitoring and responding to GitHub activity

1. Three agents run on separate infrastructure nodes, each responsible for different domains
2. When a new issue is filed on a shared repository, the relevant agent should wake up, read the issue, and either respond or create internal tasks
3. When a CI pipeline fails, the responsible agent should wake up, diagnose the failure, and either fix it or escalate
4. Agents need to check in with each other periodically (heartbeat) to detect if one has gone silent

Current state: Each of these requires a custom cron job, a polling script, a message queue, a wake invocation layer, and state deduplication logic -- per agent, per resource being monitored.

With native scheduling: Each agent has a schedule or watch directive in its definition. The system handles polling, deduplication, and session creation. The agent just defines what to check and how to respond.

Additional Context

• Related: #28221 (PostTask hook for background agent completion) addresses a related gap -- that issue covers task-level completion events within a session, while this one covers session-level scheduling and persistence across sessions. Together they would provide event-driven primitives at both levels.
• Related: #24798 (Inter-session communication) addresses sequencing between parallel sessions but not scheduled/recurring execution.
• Related: #20921 (Event subscriptions) proposes WebSocket-based real-time events, which is complementary -- subscriptions handle the "what to listen for" while scheduling handles "when to run."
• Environment: Multi-agent system with 3 persistent agents coordinating across sessions on separate infrastructure nodes. Each node runs its own Claude Code installation with shared state via git-backed memory and a messaging protocol.
• The workaround infrastructure we built is functional but represents significant engineering effort that every multi-agent Claude Code deployment will need to replicate independently. A native primitive would eliminate this entire class of infrastructure.