Author a recipe by asking AI (CLI authoring)

What it is

Omniscio treats recipes as multi-step orchestrated workflows — a recipe runs one or more Claude Code sessions in sequence, can pause for your approval mid-flow, can fan out parallel sub-prompts and consolidate them, and can be triggered manually or on a cron schedule. You can author a recipe by hand in the Recipes virtual project (Add Recipe → JSON or step-builder UI), or you can describe what you want to an external AI — Claude.ai in a browser, ChatGPT on your phone, or a Claude Code session in any project — and it will draft, validate, and save the recipe for you.

The external AI uses the omniscio-control skill, which reads the auto-delivered token from ~/.amc/cli-token and POSTs to Omniscio's local control server at 127.0.0.1:19519. Every CLI-saved recipe lands in the Omniscio inbox with approvalStatus: "pending" and refuses to run until you approve it — both manual RECIPE_START IPC calls and the cron-style scheduler tick loop gate on the approval state, so a malicious or buggy AI cannot silently execute work on your machine.

This page describes the CLI authoring path (external AI → HTTP → Omniscio). For the in-app NL drafter that the Omniscio UI uses internally, see use-recipe-drafter.md. For what recipes do at runtime and the bundled pattern catalog, see use-recipes.md.

Where to find it

Where it shows up in Omniscio

• Inbox: pending recipe approvals appear under Recipe authoring approvals with the recipe's name, step count, and Approve / Reject buttons. Approving flips the status; rejecting hides it. Either way, the row clears from the pending list.
• Recipes virtual project (sidebar): pending recipes show with an amber "Pending approval" badge instead of the usual run button. Approved recipes are runnable; rejected recipes show a red badge until you delete or revise them.
• Toast notification: when a CLI agent saves a recipe, the renderer fires RECIPE_AUTHORING_APPROVAL_NEEDED push, which surfaces a low-priority toast ("Recipe ‹name› awaiting approval") so you don't have to be staring at the inbox to notice.

How it behaves

How to use it

1. Enable CLI Control once. Omniscio → Settings → CLI Control → toggle on. Omniscio writes your bearer token to ~/.amc/cli-token (Windows: %USERPROFILE%\.amc\cli-token) with hardened file permissions, and starts the local HTTP server on 127.0.0.1:19519.

2. Ask an AI in plain English. In Claude.ai, ChatGPT, or any Claude Code session say something like:

   • "Build me a recipe that audits my newsletter inbox each morning and writes a Markdown digest."
   • "Create a recipe that fans out 5 sub-prompts on a research question, then consolidates them."
   • "In my newsletter audit recipe, change step 2's prompt to include the day-of-week."

   The omniscio-control skill auto-activates on trigger phrases like build me a recipe, set up an orchestration, add a step to my X recipe, audit my Y inbox, fan out N sub-prompts, tweak the prompt in.

3. Answer the skill's questions. It batches one round of clarifying questions (max 5): what should the recipe do, what triggers it (manual, schedule, message), should any step pause for approval, any prompts to anchor on, any pre-existing recipe to start from. Then it checks the bundled pattern library first — if a pattern fits (e.g. inbox-triage, pipeline-expansion, fan-out-consolidate), the skill instantiates from the pattern instead of synthesizing from scratch.

4. Watch the validation pass. The skill posts the draft to POST /recipe/validate and surfaces any errors back to you. You can either tell it how to fix them or accept its auto-fix proposal.

5. Approve in the Omniscio inbox. The skill posts to POST /recipe/save. The new recipe appears in your Omniscio inbox under Recipe authoring approvals with the recipe's name, step count, and Approve / Reject buttons. Until you approve, Omniscio refuses to run the recipe — the RECIPE_START IPC handler returns an error and the cron scheduler skips the recipe on every tick. Click Approve to arm it.

6. Iterate without re-creating. "Tweak step 2's prompt" → the skill calls GET /recipe/configs/:id, edits the config, then calls PUT /recipe/configs/:id. Behavioral edits (steps, pipelines, parameters, supervisors, limits) reset the recipe back to pending so you re-approve. Cosmetic edits (name, description) leave approval as-is.

Rate limit: AI-driven mutations are capped at 10/min, shared across cron jobs, automation rules, recipe drafts, validations, saves, and updates. The skill surfaces 429s when you hit it. Read-only GET requests don't count.

What the approval gate actually blocks

When a recipe's approvalStatus is pending or rejected:

• RECIPE_START IPC (manual run from the Recipes UI) returns an error envelope. The renderer surfaces "Approve before running".
• The scheduler tick loop skips the recipe entirely — even if it has a cron-style schedule attached (e.g. saved as a cron job referencing recipeConfigId).
• Sub-recipe spawns triggered from another recipe's step also gate on the sub-recipe's approval state.
• Agent-trigger HTTP (POST /recipes/run on the CLI control server) refuses to dispatch — even if the recipe has agentTriggerable.enabled: true. The two gates are orthogonal: the user opts a recipe into agent-firing once via the toggle, but every individual recipe still has to clear the authoring approval gate before any path (manual, scheduled, sub-recipe, agent-trigger) can run it.

Approval is idempotent: re-approving an already-approved recipe is a no-op (no extra notification, no state churn). Rejecting flips status to rejected; a subsequent behavioral edit (PUT with steps/pipelines/parameters/supervisors/limits changed) flips it back to pending so you can review the revision.

Operator FAQ

• "I approved, can I edit later?" Yes — edit the recipe in the Recipes UI or have the AI PUT a change. Behavioral edits reset approval; cosmetic edits don't. You'll see "Pending approval" again if the change is behavioral.
• "I rejected by mistake, what now?" Open the Recipes virtual project, find the recipe, and either revise it (the next behavioral edit flips it back to pending) or delete it and re-author from scratch.
• "What if the AI keeps draft-saving without me approving?" There's no fixed cap on saved recipes today. If the inbox queue grows uncomfortable, reject or delete the ones you don't want — the cap that DOES exist is on automation rules (20 pending CLI rules), not recipes. Cron jobs are no longer capped by count either — creation is bounded by the CLI server's shared mutation rate limit instead.
• "Can the AI bypass the gate by sending approvalStatus: 'approved'?" No. The server forces pending on every POST /recipe/save regardless of body content. On PUT /recipe/configs/:id, the server computes the next state from a behavioral diff against the existing recipe and ignores any client-supplied approvalStatus. The gate is enforced server-side, not client-side.
• "Can I see what the AI sent before I approve?" Yes — the inbox card includes the recipe's name, step count, and a "View JSON" link that shows the full saved config. Reject if anything looks off.

For agents

How it works (under the hood)

The CLI control server is implemented by /src/main/services/cli/cli-server.ts. On startup it binds 127.0.0.1:19519 and writes the bearer token to ~/.amc/cli-token with hardened permissions (Unix 0o600, Windows ACL grant). The recipe routes are registered by registerRecipeRoutes() in /src/main/services/cli/cli-server-recipe-routes.ts (wired from register-cli-routes.ts at startup):

• GET /recipe/patterns and GET /recipe/patterns/:id — read-only, list bundled patterns from resources/recipe-patterns/
• POST /recipe/draft — translates NL to a RecipeConfig via RecipeDrafterService (mirrors the RECIPE_CREATE_FROM_NL IPC); rate-limited
• POST /recipe/validate — runs runSemanticChecks + runWarningChecks + estimateRun; rate-limited
• GET /recipe/configs and GET /recipe/configs/:id — read-only, list/find saved recipes (global + per-project, deduplicated)
• POST /recipe/save — persists via recipeFileStore.saveRecipeConfig; forces approvalStatus: 'pending' server-side regardless of body; emits RECIPE_AUTHORING_APPROVAL_NEEDED push so the renderer's inbox refreshes, plus RECIPE_CONFIG_CHANGED (RT-F005) so open Recipes lists live-refresh; returns 201
• PUT /recipe/configs/:id — looks up the existing recipe, normalizes both sides through recipeSaveConfigSchema, compares behavioral fields (steps, pipelines, parameters, supervisors, limits) via stableStringify; resets approval to pending only when behavioral fields changed AND the current state is approved or rejected; emits the approval push when reset fires, and always emits RECIPE_CONFIG_CHANGED (RT-F005) so open lists refresh; returns 200

The approval state machine is 'not_required' | 'pending' | 'approved' | 'rejected' (with undefined treated as legacy back-compat). The runtime gate lives in three places, all routing through the shared checkRecipeApprovalStatus helper in /src/main/services/recipe/recipe-validation.ts so the contract — pending / rejected refuse, approved / not_required / undefined proceed — cannot drift between surfaces: (1) the RECIPE_START IPC handler in /src/main/ipc/recipe-handlers.ts (manual run from the Recipes UI), (2) the tick loop in /src/main/services/recipe/recipe-scheduler-service.ts (filters non-approved recipes out before scheduling), and (3) handleRecipeTriggerViaCli in /src/main/ipc/recipe-handlers.ts (the agent-trigger CLI path that backs POST /recipes/run). The user's approve/reject decisions flow back through the RECIPE_AUTHORING_RESPOND IPC handler in /src/main/ipc/recipe-authoring-handlers.ts, which writes the new approvalStatus to disk via recipeFileStore.saveRecipeConfig and emits a RECIPE_CONFIG_CHANGED push (RT-F005) so any other open Omniscio window's recipe list stays in sync.

The RecipeConfig.approvalStatus field is defined in /src/shared/types.ts and validated by recipeSaveConfigSchema in /src/shared/ipc-schemas.ts. The skill that external AIs follow is the omniscio-control bundle — its recipes surface doc walks the full authoring flow (clarify → check patterns → draft → validate → save → iterate) end-to-end.

Related

• use-recipes.md — what a RecipeConfig looks like and how runtime execution works
• use-recipe-drafter.md — the in-app NL drafter (RECIPE_CREATE_FROM_NL IPC) that Omniscio's own UI uses
• cli-control.md — the CLI control server in general, all endpoints
• create-cron-job-with-ai.md — the same authoring pattern, applied to cron jobs
• automations-and-auto-replies.md — the same authoring pattern, applied to automation rules
• .claude/skills/omniscio-control/recipes.md — the skill external AIs follow when authoring on your behalf