Scheduled Tasks (Rituals)

Scheduled Tasks are called Rituals in the desktop app. A Ritual is a workspace-specific automation rule that runs a Grunt prompt on a cadence. A Grunt is the base CLI agent, such as Claude Code, Codex, Antigravity CLI (agy), Cursor, or a custom agent you configured in Armoury. To add, edit, or install Grunts, see Agents and Tasks.

Each Ritual run launches a real terminal session, so you can watch output live, halt it, inspect the result, and review run history later. Rituals are saved in the workspace file under code-overlord.scheduledTasks, which means every stronghold (workspace) can have its own automation setup.

Important: Rituals launch a configured Grunt directly. They are not Minion runs, although they appear in the same Action workspace and can be monitored like other agent terminals.

What A Ritual Contains

Each Ritual stores:

Field	Meaning
Title	The human-readable Ritual name.
Grunt	The base CLI agent that will run the prompt.
Decree	The prompt body sent to the Grunt.
Cadence	The recurring schedule.
Enabled state	Whether automatic runs are allowed.
Omens	When notifications should appear.
Working directory	Optional; otherwise Code Overlord resolves an appropriate workspace folder.

Where To Find Rituals

Rituals live inside the Action workspace. The RITUALS section sits in the left Action sidebar (below your agents and Quests), and every run opens a live terminal in the centre panes just like any other agent session.

Rituals are part of the normal Action workspace: the RITUALS section lives in the left sidebar, and each run surfaces as a live terminal you can watch, halt, and review.

Open a workspace, then use the RITUALS section in the Action sidebar. The section appears with a count, for example RITUALS (3), and has a + button for creating a new Ritual.

The section shows:

• A status dot for each Ritual.
• The Ritual name.
• A next-run hint when the Ritual is enabled and not currently running.
• A running count such as 1/3 active when a run is active.

Click a Ritual row to open its detail panel. Right-click a row for quick actions.

Create A Ritual

1. Open a workspace.
2. In the Action sidebar, find RITUALS.
3. Click the + button. Its tooltip is Create a new ritual.
4. In New Ritual, fill Title.
5. Choose a Grunt. If none is selected, the control says Choose thy grunt.
6. Pick a Cadence.
7. Choose Omens: Always, On failure, or Never.
8. Write the Decree prompt.
9. Optional: click Foresee to preview variable substitution.
10. Click Inscribe Ritual.

The save button is disabled until the Title, Decree, and a periodic cadence are valid. The inline hint explains what is missing: Title is required, Decree is required, or Select a periodic cadence.

Edit A Ritual

Open a Ritual detail card and click Edit. The modal title changes to Edit Ritual, and the save button changes to Seal Amendments.

Use Retreat to cancel without saving. Pressing Esc also closes the modal unless the inline file picker is active; when the file picker is active, Esc closes the picker first.

Cadence Options

The desktop editor supports these periodic schedules:

Cadence option	Configuration
Every N min	Drag value from 1 to 120 minutes.
Every N hours	Drag value from 1 to 24 hours.
Daily	Pick an HH:MM time.
Weekdays	Pick an HH:MM time for Monday through Friday.
Weekly	Pick a weekday and HH:MM time.

Older imported configs may contain event-driven schedules such as on-open, commit, branch change, or file change. The current desktop editor requires a periodic cadence before it can save amendments, and shows the warning:

An ancient trigger of yore hath been unearthed. Pray, select a proper cadence.

Decree Prompt Variables

The Decree editor supports these variables:

Variable	Resolves to
{workspace_name}	The current workspace name.
{repos}	Workspace repository list/context.
{branch}	Current branch context when available.
{datetime}	Current date/time at execution.

Click Foresee to show The decree, as it shall be spoken: with a preview of the substituted prompt. Click Hide Prophecy to collapse the preview.

File Mentions In The Decree

While editing the Decree, type @ inside a token to open the file picker. The picker searches workspace paths, shows up to 10 matches, and inserts a relative workspace path.

Controls:

• Arrow Up / Arrow Down: move through matches.
• Enter: insert the selected path.
• Escape: close the picker.

Notification Omens

Omens are the notification policy for a Ritual run.

Omen	Meaning
Always	Notify on successful and failed runs.
On failure	Notify only when a run fails. This is the default for new Rituals.
Never	Do not notify for that Ritual.

Run, Halt, Enable, Disable

From a Ritual row's right-click menu:

• Dispatch Now: run the Ritual immediately.
• Halt the running grunt: stop the currently running session, shown only when a run is active.
• Disable or Enable: toggle automatic scheduling.

From the detail panel:

• Click the status dot beside the Ritual name to enable or disable it.
• Click Dispatch Now to run immediately.
• Click Edit to amend it.
• Open the ... menu and choose Banish to delete it.

Deleting opens Confirm banish? with the prompt Banish ritual "{name}"? This cannot be undone.

Detail Panel And Run History

Clicking a Ritual opens a compact right-panel card. The card header reads like:

Rituals / [status dot] [Ritual name]

The card shows:

• Schedule
• Grunt
• Next run
• Status
• Prompt excerpt

Status values include:

Status	Meaning
Running	A Grunt session is currently active for this Ritual.
Success	The last completed run succeeded.
Failed - ...	The last completed run failed; hover for longer error text when truncated.
Idle	No current run and no completed history yet.
Disabled	Automatic runs are off.

The detail card has a chevron to collapse or expand its metadata. Below the card, Run History can be expanded or collapsed. It shows the currently running entry and up to recent completed entries. Successful runs are labelled Conquered; failed runs are labelled Fallen. If there is no history, the panel says No runs yet.

Where Results Land

Each Ritual run creates a normal terminal session:

• The live run appears in the Action workspace so you can watch output.
• The run is tagged with the Ritual ID for sidebar/detail association.
• Completed result metadata is persisted in scheduled run history.
• Cloud snapshots are published when cloud sync/remote scheduling is active, so phone or remote views can see current Ritual state.
• Prompt files for launch handoff are written under the app's scheduled prompt storage.

For Bash-like Grunts, the scheduler sends the prompt as initial shell input. For AI agent Grunts, the scheduler uses the agent launch-task prompt path.

How Scheduling Works

The control-plane scheduler checks workspace Rituals regularly and fires due tasks only when this control plane owns scheduling authority for the workspace. With cloud/remote handoff, this prevents both local desktop and Skyforge from launching the same occurrence at once.

Practical behavior:

• Disabled Rituals do not run automatically.
• Dispatch Now can run a disabled Ritual because it is an explicit manual action.
• A run occurrence is claimed before launch to avoid duplicate firing.
• A startup grace window prevents immediate noisy launches while the control plane is still settling.
• Completion is recorded when the terminal exits or when the scheduler sees the session become idle for the completion window.
• Run history is kept and pruned by the scheduler state.

Skyforge And Remote Notes

Rituals can run under local desktop authority or remote VM authority, depending on workspace scheduling ownership. Skyforge is Code Overlord's remote-execution lane (a cloud VM). For how remote compute and phone/desktop sync work, see Cloud Sync.

Check these when a Ritual is meant to run remotely:

• The workspace has valid cloud/remote authority.
• The remote VM is ready.
• The selected Grunt exists and can launch on the remote side.
• The working directory can be mapped to a remote path.
• Required profile secrets are available to the remote launch path.

If authority is transferring, unavailable, or owned by another control plane, the scheduler records a blocked/failure state instead of silently double-running the task.

Suggested Rituals

Good Ritual prompts are specific, bounded, and easy to judge from the terminal output.

Examples:

• Review uncommitted changes every 30 minutes and report only risky diffs.
• Summarize workspace status every weekday morning.
• Check dependency drift once a day.
• Run a branch health check every two hours.
• Ask a code-review Grunt to inspect recently changed files and produce a short findings list.

Troubleshooting

Problem	What to check
The + button is missing	Open a workspace first and check that the Action sidebar has loaded Ritual state.
Inscribe Ritual is disabled	Fill Title, Decree, and choose a periodic cadence.
A legacy schedule will not save	Select one of the current periodic cadence options.
The Ritual does not run automatically	Confirm it is enabled, due, and owned by the current scheduling authority.
Manual Dispatch Now fails	Check the selected Grunt command, workspace path, Skyforge readiness, and run history error.
A remote Ritual fails before launch	The remote cwd may be unmapped, the Grunt may be missing remotely, or required secrets/profile values may be unavailable.
A run appears stuck	Open the live terminal if present, then use Halt the running grunt from the row context menu if needed.
No run history appears	The Ritual may never have completed, or the current workspace/control plane may not have loaded persisted scheduled history yet.

Tips

• Start with a 30-minute or hourly cadence until you know how noisy the prompt is.
• Prefer On failure Omens for recurring quality checks.
• Keep Decrees bounded: ask for a summary, findings, and a clear stop condition.
• Use file mentions with @ when a Ritual should repeatedly inspect the same paths.
• Use Dispatch Now after editing to verify the Decree before relying on the cadence.