Holix Cron

---
name: holix-cron
description: Schedule recurring agent tasks via Holix built-in gateway cron (not crontab or custom scripts)
tags:
  - cron
  - schedule
  - holix
  - gateway
  - periodic
  - automation
user-invocable: true
---

## When to use this skill

The user wants a **recurring or scheduled task** (daily report, hourly check, weekly backup summary, etc.).

**Always use Holix built-in cron** — jobs stored in the profile and executed by the gateway scheduler with the same agent stack as chat.

## Do NOT

- Do **not** create or edit system `crontab`, `launchd` plists, or `systemd` timers for Holix agent work.
- Do **not** write standalone Python/bash “scheduler” scripts that loop with `sleep` unless the user explicitly needs OS-level scheduling outside Holix.
- Do **not** suggest third-party job runners when `holix gateway` can run the task.

## Prerequisites

1. **Gateway must be running** (scheduler lives inside gateway):
   - `holix gateway start` (background) or `holix gateway start -f` (foreground)
   - `holix gateway status` — verify running
2. Jobs are **per profile** (`--profile` / `HOLIX_PROFILE`).

## Storage (read-only for debugging)

- Jobs: `~/.holix/profiles/<profile>/data/cron/jobs.json`
- Run log: `~/.holix/profiles/<profile>/data/cron/runs.log`

Prefer **commands** below; edit JSON only if the user insists.

## How to create a job

Tell the user the slash command (TUI / Telegram) or run CLI yourself if you have shell access.

**Slash (chat):**

```
/cron add <schedule> :: <task description>
```

Examples:

- `/cron add every day at 9 :: Summarize yesterday's git activity`
- `/cron add every 30 minutes :: Check disk space and alert if >90%`
- `/cron add 0 9 * * 1-5 :: Morning standup prep from open issues`
- `/cron add hourly :: Quick health check of gateway`

**CLI (terminal):**

```bash
holix cron add "every day at 9 :: Summarize logs"
holix cron list
holix cron disable <job-id>
holix cron enable <job-id>
holix cron remove <job-id>
```

### Schedule formats

- **Natural language** (parsed automatically): `every day at 9:00`, `every 30 minutes`, `hourly`, `daily`, `weekly`, `weekdays`, `every 2 hours`
- **5-field cron** (minute hour day month weekday): `0 9 * * *`, `*/15 * * * *`

Task text after `::` is the **agent prompt** for each run (be specific: what to check, output format, workspace assumptions).

## Manage jobs

| Action | Slash | CLI |
|--------|-------|-----|
| List / UI | `/cron` or `/cron list` | `holix cron list` |
| Enable | `/cron enable <id>` | `holix cron enable <id>` |
| Disable | `/cron disable <id>` | `holix cron disable <id>` |
| Delete | `/cron remove <id>` | `holix cron remove <id>` |

Job IDs are short strings shown in the list (prefix match works).

TUI opens a modal with enable/disable/delete. Telegram has inline buttons under `/cron`.

## Execution behavior

- Scheduler tick runs inside **gateway** (~30s); due jobs start in the background.
- Each run uses conversation id `cron-<job-id>` (separate from the user's chat session).
- The runner prepends context that this is an **automated** run; the model should complete the task and **summarize** results.
- Status fields: `last_run_at`, `last_status` (`success` / `error` / `running`), `next_run_at`, `run_count`.

## Auto-creation from chat

Holix **automatically creates** a cron job when the user writes a **recurring** request in natural language (Telegram, MAX, TUI), for example:

- «Присылай мне новости по теме X каждый день в 10 утра»
- «Send me a summary every day at 9»

No `/cron add` needed for clear schedule + task phrasing. The host replies with job id and `next_run_at`. Gateway must still be running for execution.

You can also call the **`schedule_cron`** tool (`schedule` + `task`) when auto-detection did not fire.

## Workflow for the agent

1. Clarify **what** should run and **how often** (timezone: server UTC for croniter unless user specifies).
2. Draft a **clear task prompt** (one-shot instructions, no “ask me later”).
3. Prefer **`schedule_cron`** tool or let the host auto-create; otherwise `/cron add …` or `holix cron add "…"`.
4. Remind to start gateway if not running: `holix gateway start`.
5. After creation, suggest `/cron list` to verify `next_run_at`.

## Natural language → user request

If the user says “every Monday at 10 run X”, translate to:

```
/cron add every week :: X
```

(or `0 10 * * 1 :: X` if they prefer explicit cron).

## Troubleshooting

| Problem | Check |
|---------|--------|
| Job never runs | `holix gateway status`; gateway must be up |
| Invalid schedule | Use `every day at 9` or valid 5-field cron |
| Task runs but fails | Read `runs.log`; fix prompt or model/profile config |
| Duplicate jobs | `/cron list`; remove old rule with `/cron remove` |

## Related Holix commands (not cron)

- `/init` — one-shot project analysis, not periodic
- `holix hub` — skills/plugins, not scheduling