Cron & scheduling

Cron jobs run agent tasks on a schedule. Each job is a natural-language prompt plus a schedule; on fire, it runs in its own session and the result is delivered to your Slack DM and/or the dashboard notifications panel.

Open the Schedule panel in the dashboard and click Add. Fill in a name, the prompt, and the schedule (interval or cron expression). You can also just ask in chat: "Every weekday at 9, summarize my open work" — the agent creates the job for you.

kirocrew cron add "briefing" "give me a morning status report" --cron "0 9 * * 1-5"
kirocrew cron add "poll-status" "check the pipeline endpoint" --every 300

The agent itself calls the equivalent MCP tool (cron_add) whenever you say something like "remind me every morning to check…". No syntax to memorize.

The Schedule panel shows all jobs with their status, next-run time, and controls: pause, resume, trigger now, edit, delete.

kirocrew cron list
kirocrew cron pause <job_id>
kirocrew cron resume <job_id>
kirocrew cron trigger <job_id>       # run once manually
kirocrew cron remove <job_id>
kirocrew cron remove-all

All of these are exposed as MCP tools too (cron_list, cron_pause, cron_resume, cron_trigger, cron_remove, cron_remove_all).

Cron expressions accept the usual five-field format: minute, hour, day-of-month, month, day-of-week.

Every job can be tuned:

By default, cron jobs get a small random delay before firing. This spreads load when many jobs share a schedule and prevents everyone hitting the same endpoint at exactly HH:00:00. Opt out with --strict-schedule.

• Fresh (default) — every run starts a new session. Context from previous runs doesn't leak in.
• Persistent — the same session is reused. Useful when the job builds up context over time (e.g. "poll a status endpoint every 5 min and remember what you saw").

Fresh runs are safer for parallel or unrelated work. Persistent runs are more efficient for a long-running observer.

Each job's output is delivered to your Slack DM (if configured) and to the dashboard notifications panel.

You can override delivery per-run with deliver: markers in the prompt or in HEARTBEAT.md:

- [ ] Monitor pipeline for failures  <!-- deliver:C0123CHANNEL -->

This routes the result to a specific Slack channel instead of your DM.

Cron jobs persist to ~/.kiro/crew/crons.json and load at gateway startup. The scheduler runs continuously — as long as the gateway is running, jobs fire on schedule.

If the gateway is down when a job would have fired, the run is missed. There's no catch-up on restart — this is a scheduler, not a queue.

Some multi-instance setups don't want the cron scheduler active. Start the gateway with --no-crons to skip it:

kirocrew gateway --no-crons

Jobs are still readable via kirocrew cron list, but they won't fire on this instance.

Cron jobs that trigger the Task Runner don't show up in the dashboard Tasks page — they're filtered out to keep the view focused on user-initiated work. The tasks still run; the state is just hidden from the visible list.

Cron runs are unattended by definition, so they never carry per-run trust. Any tool call inside a cron job:

• Never gets dashboard-only "auto-approve this session" trust
• Still respects hook deny-lists, sensitive-path blocks, and governance policies
• Still respects the global YOLO override if it's active

Extending per-run trust to recurring runs is deliberately not supported — recurring auto-approval is a bigger risk than a single interactive session.

Heartbeats let Crew watch something over time without you babysitting a session. Ask in chat — "watch this PR and tell me when comments land" or "monitor the pipeline and alert if it goes red" — and Crew creates a heartbeat task that checks every 60 seconds.

Unlike cron jobs (which run a prompt on a fixed schedule), heartbeats are reactive — they only surface results when something changes.

Heartbeat tasks live in ~/.kiro/crew/workspace/HEARTBEAT.md. The heartbeat service reads the file every 60 seconds, runs all tasks in parallel, and:

• On success — clears the task (condition was met)
• On failure — writes it back for retry on the next tick
• On delivery — routes results to your configured surface

By default, results go to your Slack DM or dashboard notifications. Override per-task with a delivery marker in the heartbeat file: <!-- deliver:C0123CHANNEL --> routes to a specific Slack channel.

External systems can trigger Crew agent sessions over HTTP. A CI pipeline can notify Crew when a build fails, or a monitoring tool can escalate an alert — all without someone at the terminal.

The endpoint:

POST /api/hooks/agent
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "Build failed for pipeline X. Check logs and report the root cause."
}

Requests need a valid Bearer token (mint one with kirocrew token). Up to 6 concurrent webhook sessions; each has a 10-minute default timeout.

Example — CI failure alert:

curl -X POST http://localhost:5476/api/hooks/agent \
  -H "Authorization: Bearer $KIROCREW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Build failed. Summarize what went wrong."}'

Crew analyzes the failure and responds. The result routes to your configured notification surface.

For persistent workflows that carry context across multiple webhook calls (e.g., a multi-stage pipeline), the agent can use register_hook to save workflow state that the next webhook call picks up.

For monitoring that stays within a live session (rather than a background heartbeat), Crew has autonudge — a self-check loop that re-injects your instructions on an idle timer.

Use it when you want Crew to keep checking something in your current conversation:

• "Keep checking this every 5 minutes and tell me if it changes"
• "Babysit this deploy and alert me when it's done"

Autonudge works from dashboard chat, Slack threads, and Discord DMs. Stop it by sending a new message that takes over the session, or with the autonudge_stop tool.