Scheduler Backend Action

Run a scheduled job as one headless turn through an external coding-CLI backend (Claude Code, Codex, Gemini, Grok) — no in-process agent, no model turn

Attach a backend to a scheduled job to run its message as one headless turn through a registered CLI backend — no native agent is resolved, and no in-process model turn is taken.

A backend job is a model-free action: it delegates the whole turn to a coding-CLI (claude-code, codex-cli, gemini, grok) that owns its own subscription — ideal for a nightly refactor or a scheduled review in a pinned repo.

Quick Start

1. CLI

   Add a job with --backend. Its message runs as one headless CLI turn — no agent, no in-process model turn.

   praisonai schedule add "nightly-refactor" \
     -s "cron:0 2 * * *" \
     -m "tidy utils.py, run tests" \
     --backend claude-code \
     --backend-cwd ~/proj \
     --deliver telegram

2. Python

   Set backend on a ScheduleJob. backend_options carries overrides like cwd and timeout_ms.

   from praisonaiagents.scheduler import ScheduleJob, Schedule, DeliveryTarget
   
   job = ScheduleJob(
       name="nightly-refactor",
       schedule=Schedule(kind="cron", cron_expr="0 2 * * *"),
       message="tidy utils.py, run tests",
       backend="claude-code",
       backend_options={"cwd": "/path", "timeout_ms": 300000},
       delivery=DeliveryTarget.parse("telegram"),
   )

How It Works

The executor resolves the backend through the _code_bridge seam before any agent — a backend job never resolves a native agent and never takes an in-process model turn.

Choosing the Right Mode

A scheduled job runs in one of four modes depending on which fields are set.

command and backend are mutually exclusive — a job runs exactly one model-free action:

--command and --backend are mutually exclusive: a job runs exactly one model-free action. Configure one or the other.

Configuration Options

ScheduleJob fields

backend docstring:

Optional external coding-CLI backend id (e.g. "claude-code", "codex-cli"). When set, the job’s message is executed as one headless turn through the named backend from the backend registry — no native agent is resolved and no in-process model turn is taken. Like command, this is a trusted operator-configured action: it spawns a host CLI subprocess and is deliberately not exposed on the LLM-callable scheduling tools. Additive and backward-compatible: jobs without a backend are unchanged.

backend_options docstring:

Optional mapping of overrides for the backend run. Recognised keys are validated by the executor/backend (e.g. cwd for the working directory, timeout_ms for the subprocess bound); unknown config overrides are rejected at resolution time rather than silently ignored.

Behavior notes

• Prereq: requires pip install praisonai-code. If missing, the tick is recorded as failed with the remediation: CLI backend '<id>' unavailable: <e>. Backend jobs require the praisonai-code package (pip install praisonai-code).
• Default timeouts: the backend’s own timeout_ms (backends default to 300s); the executor adds a 30s belt-and-braces asyncio.wait_for on top.
• Output cap: stdout is bounded to the same 8,000-char cap as --command.
• --model on a backend job is passed as an input to the CLI (e.g. codex -m gpt-5-codex, grok --model ...) — not a drift guard. Pinning is otherwise skipped for backend jobs.
• Delivery: identical routing to --command / agent jobs (Telegram, Discord, Slack, WhatsApp, all, origin, platform:chat_id[:thread]).

Common Patterns

Nightly refactor (Claude Code)

Run a nightly clean-up turn through claude-code in a pinned repo.

praisonai schedule add "nightly-refactor" \
  -s "cron:0 2 * * *" \
  -m "tidy utils.py, run tests" \
  --backend claude-code \
  --backend-cwd ~/proj \
  --deliver telegram

Codex daily fix

Run a daily fix turn through codex-cli, pinning the model.

praisonai schedule add "codex-daily-fix" \
  -s daily \
  -m "fix the failing tests in src/" \
  --backend codex-cli \
  --model gpt-5-codex \
  --deliver slack:C012345

Gemini review in a pinned repo

Run a scheduled review through gemini in a fixed working directory.

praisonai schedule add "gemini-review" \
  -s "cron:0 18 * * 1-5" \
  -m "review today's diff and summarise risks" \
  --backend gemini \
  --backend-cwd /srv/repo \
  --deliver telegram

Grok subscription-backed turn

Run a scheduled turn through grok, bounded with --backend-timeout.

praisonai schedule add "grok-brief" \
  -s daily \
  -m "summarise open issues" \
  --backend grok \
  --backend-timeout 600 \
  --deliver telegram

Best Practices

pip install praisonai-code

praisonai schedule add "big-refactor" -s daily \
  -m "refactor the payment module" \
  --backend claude-code --backend-timeout 1200 \
  --deliver telegram

Related