# Schedule

> Use when create, list, or manage scheduled or recurring tasks

- **Type:** Skill
- **Install:** `agentstack add skill-fangxm233-cortex-agent-schedule`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fangxm233](https://agentstack.voostack.com/s/fangxm233)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fangxm233](https://github.com/fangxm233)
- **Source:** https://github.com/fangxm233/cortex-agent/tree/main/agent-server/defaults/plugins/cortex-system/skills/schedule

## Install

```sh
agentstack add skill-fangxm233-cortex-agent-schedule
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Schedule

You are Cortex, managing the scheduled task system.

## Arguments
$ARGUMENTS

Scheduled tasks allow Cortex to automatically execute messages at set times — like a recurring GPU check, daily standup, or delayed reminder. Tasks persist in `agent-server/schedules.json` and survive daemon restarts.

**Task types:**
- `interval` — repeat every N duration (30s / 5m / 2h / 1d)
- `daily` — every day at a fixed time (HH:MM, 24-hour)
- `weekly` — every week at a fixed day + time (`mon 21:00`)
- `once` — run once after a delay, then auto-removed

**Targets (where the fired task lands):**
- `fresh` *(default)* — new isolated thread + new session (current behavior; safest for unrelated tasks)
- `current-project` — spawn a fresh session in the project (default for project-addressed schedules)
- `current-thread` — continue the current thread (only valid while it's running/waiting)

`current-*` shorthand resolves to concrete IDs at create time, so `cortex_schedule_list` always shows real IDs.

---

## Preferred Path — MCP Tools (LLM-driven)

When you (the LLM) need to add or manage schedules from inside an agent session, use these MCP tools — they're more reliable than shelling out to `bin/schedule` (no quoting issues, no working-dir confusion):

```
mcp__cortex__cortex_context()
  → { sessionId, sessionName, threadId, profile, project, backend, ... }

mcp__cortex__cortex_schedule_add({
  type: 'interval' | 'daily' | 'weekly' | 'once',
  message: 'prompt to fire',
  interval?: '30m' | '2h' | ...,            // for interval
  time?: '09:00',                            // for daily/weekly
  dayOfWeek?: 'mon' | 0-6,                   // for weekly
  delay?: '2h' | '90m',                      // for once
  target?: 'fresh' | 'current-project' | 'current-thread' | { kind, ... },
  fallback?: 'fresh' | 'skip' | 'wait',      // when target thread is gone at fire time
  profile?: 'fast-worker',
  channel?: 'C123',                          // override; defaults to current context
})
mcp__cortex__cortex_schedule_list({ limit? })
mcp__cortex__cortex_schedule_get({ id })
mcp__cortex__cortex_schedule_remove({ id })
mcp__cortex__cortex_schedule_pause({ id })   // recurring only
mcp__cortex__cortex_schedule_resume({ id })
```

**Worked examples:**

> User: "Remind me to run /orient every morning at 9, send results to current channel"
>
> Call `mcp__cortex__cortex_schedule_add({ type: 'daily', time: '09:00', message: '/orient', target: 'current-project' })` — done. No need to call `cortex_context` first; the shorthand resolves automatically.

> User: "Report training status in this thread after 30 minutes"
>
> Call `mcp__cortex__cortex_schedule_add({ type: 'once', delay: '30m', message: 'Check training results on  and report', target: 'current-thread' })` — the schedule continues the current thread (valid while it is running/waiting), so prior context is intact.

> User: "Run deep retrospective every Monday at 9 PM"
>
> Call `mcp__cortex__cortex_schedule_add({ type: 'weekly', dayOfWeek: 'mon', time: '21:00', message: '/deep-retrospective' })` — `target` defaults to `fresh`, which is the right choice for a standalone weekly job.

If `current-thread` is requested but the context lacks the field, the tool throws — it does NOT silently fall back to fresh. Re-issue with `target: 'fresh'` if that's actually what you want.

---

## Canonical CLI Usage

The canonical CLI usage is:

```bash
npx tsx agent-server/src/schedule-cli.ts --help
npx tsx agent-server/src/schedule-cli.ts list
npx tsx agent-server/src/schedule-cli.ts get 
npx tsx agent-server/src/schedule-cli.ts set interval  
npx tsx agent-server/src/schedule-cli.ts edit|update  [--message ] [--profile ] [--channel ] [--time ] [--day ] [--run-at ] [--interval ]
npx tsx agent-server/src/schedule-cli.ts pause 
npx tsx agent-server/src/schedule-cli.ts resume 
npx tsx agent-server/src/schedule-cli.ts remove  [--dry-run]
npx tsx agent-server/src/schedule-cli.ts add interval  
npx tsx agent-server/src/schedule-cli.ts add daily  
npx tsx agent-server/src/schedule-cli.ts add weekly   
npx tsx agent-server/src/schedule-cli.ts add once  
# Flag-mode add (alternative):
npx tsx agent-server/src/schedule-cli.ts add --type interval --interval 30m --message "Check GPU status"
npx tsx agent-server/src/schedule-cli.ts add --type daily --time 09:00 --message "Daily standup" --channel slack
```

**New CLI features:**
- `--help`: Full usage reference with copyable examples
- `remove --dry-run`: Preview which task would be removed without deleting
- Flag-mode `add`: All parameters via explicit flags (backward-compatible with positional mode)
- Error messages list valid values (e.g., unknown type → shows `interval, daily, weekly, once`)

Use the CLI when the MCP tools above are unavailable (e.g. running outside an agent session, terminal scripting, debugging).

---

## Step 1: Read Current State

Read current schedule state via the canonical schedule CLI from the current repo root (for example `npx tsx agent-server/src/schedule-cli.ts list`). If the file is missing or empty, treat as `{ "tasks": [] }`.

---

## Step 2: Determine Action

Parse `$ARGUMENTS` to choose a path:

### Path A — List / No Arguments

Use the canonical schedule CLI to list tasks and return its JSON output directly: `npx tsx agent-server/src/schedule-cli.ts list`.

If there are no tasks, the JSON result should be `{ "tasks": [] }`.

Stop after sending — no restart needed.

---

### Path B — Add a Task

Interpret the user's natural language description to determine:
- **type**: interval / daily / weekly / once
- **timing**: duration string, HH:MM time, or ` HH:MM`
- **message**: a self-contained instruction Cortex will execute when the task fires

**Interpretation examples:**
- "Check GPU status every 30 minutes" → interval, 30m, "Check GPU status (nvidia-smi) and report a one-line summary"
- "Generate a daily project report every morning at 9" → daily, 09:00, "Generate a brief daily status report for all active projects"
- "Do retrospection every Monday at 9 PM" → weekly, mon 21:00, "Execute /deep-retrospective — weekly knowledge mining"
- "Remind me to check training results in 2 hours" → once, 2h, "Check training results on  and report to user"

**Compute the new task object** using the canonical schedule CLI add command. The CLI currently defaults `channel` to `cli` unless an explicit channel override is provided.

Examples:
- `npx tsx agent-server/src/schedule-cli.ts add interval 30m "Check GPU status on  (nvidia-smi) and report a one-line summary"`
- `npx tsx agent-server/src/schedule-cli.ts add daily 09:00 "Generate a brief daily status report for all active projects"`
- `npx tsx agent-server/src/schedule-cli.ts add weekly mon 21:00 "Execute /deep-retrospective — weekly knowledge mining"`
- `npx tsx agent-server/src/schedule-cli.ts add once 2h "Check training results on  and report to user"`

Confirm the plan in the output before writing, showing:
- Task type and timing
- The message that will execute
- When it will first fire

Then write the file and proceed to Step 3.

---

### Path C — Remove a Task

Find the task with the matching id via the canonical schedule CLI and remove it with `npx tsx agent-server/src/schedule-cli.ts remove `.

If not found, output: `:x: Task \`\` not found.`

Proceed to Step 3 if a task was removed.

---

## Step 3: Report Result

The scheduler automatically watches `agent-server/schedules.json` for changes and hot-reloads timers — no daemon restart needed.

Output a confirmation:

**After add:**
```
Scheduled: every 30m — "Check GPU status on "
id: `a1b2c3d4` | first run: in 30m
```

**After remove:**
```
Removed task `a1b2c3d4`.
```

---

## Notes

- `channel` follows the canonical CLI behavior: if no explicit override is provided, new tasks default to `cli`
- Task messages should be self-contained: Cortex will receive them with the prefix `[Scheduled Task]` and must be able to act without prior context
- For daily tasks, `nextRun` = current epoch ms + ms until next HH:MM occurrence (if time has passed today, add 24h)
- For weekly tasks, store both `dayOfWeek` (`0=Sun ... 6=Sat`) and `time`, and compute `nextRun` from the next matching occurrence
- Inside this skill, prefer the canonical schedule CLI / scheduler API path rather than editing `agent-server/schedules.json` directly. The user-facing `!schedule` command remains a separate shortcut handled by the command layer.
- Do not restart the daemon after schedule changes — the scheduler hot-reloads `agent-server/schedules.json`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fangxm233](https://github.com/fangxm233)
- **Source:** [fangxm233/cortex-agent](https://github.com/fangxm233/cortex-agent)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fangxm233-cortex-agent-schedule
- Seller: https://agentstack.voostack.com/s/fangxm233
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.