Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs(ok): scheduled runs docs, agenda-routines research and spec (#3271)

tim-inkeep50aeebe2edc1
diff --git a/docs/content/get-started/overview.mdx b/docs/content/get-started/overview.mdx
index 7eb271cb7..20e002171 100644
--- a/docs/content/get-started/overview.mdx
+++ b/docs/content/get-started/overview.mdx
@@ -24,7 +24,7 @@ OpenKnowledge is three layers working together: a "WYSIWYG" editor for you, MCP
- A **built-in TUI** in the desktop app for Claude, Codex, OpenCode, and Cursor
- Graph and wiki link visualizations
- **Embeddable HTML** for writing engineering specs and visualized reports.
-- **Meeting ingestion** from Granola, Fireflies, and other recorders. On demand in any editor, or automatically with the [OpenClaw](../integrations/openclaw.mdx) gateway. See [Ingest meetings](../workflows/meeting-ingestion.mdx).
+- **Meeting ingestion** from Granola, Fireflies, and other recorders. On demand in any editor, or automatically on a schedule, from your agent's built-in scheduler or the [OpenClaw](../integrations/openclaw.mdx) gateway. See [Ingest meetings](../workflows/meeting-ingestion.mdx).
## Where to start
diff --git a/docs/content/integrations/claude-code.mdx b/docs/content/integrations/claude-code.mdx
index c33c16ba3..8cca5bd08 100644
--- a/docs/content/integrations/claude-code.mdx
+++ b/docs/content/integrations/claude-code.mdx
@@ -33,6 +33,16 @@ If Claude Code doesn't use the OpenKnowledge `exec` tool, restart it so it picks
When Claude Code writes to a doc, you'll see the change land live in OpenKnowledge. Just ask Claude Code to open it for you.
+## Scheduled runs
+
+Claude Code can work your knowledge base on a schedule (a nightly consolidation pass, a morning meeting sync) without OpenKnowledge shipping a scheduler of its own. Three tiers, as of August 2026. Anthropic's scheduler surfaces are moving quickly, so check the linked docs before you rely on a specific limit:
+
+- **[Desktop scheduled tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks).** Claude Desktop's **Routines** page schedules local runs (choose **Local** when creating one) down to the minute. They see your local files and MCP servers, so an OK project works as-is. Tasks fire only while the app is open and your computer is awake.
+- **[Cloud routines](https://code.claude.com/docs/en/routines) (`/schedule`).** These run on Anthropic's infrastructure against a fresh clone of a GitHub repo and see only what is committed: no local files, no locally-registered MCP servers. Reaching OK from a routine takes both halves, a committed `.mcp.json` declaring `open-knowledge` and a setup script in the routine's environment that installs the CLI. If you ran `ok init --local-only` or unshared later, `.mcp.json` sits in `.git/info/exclude` and never reaches the clone, so this tier needs the default shared posture. Minimum schedule interval is one hour.
+- **OS cron + `claude -p`.** A plain cron job running `claude -p "<prompt>"` in the project loads the committed skill, `.mcp.json`, and CLAUDE.md the same way an interactive session does. That depends on `-p` staying non-bare: [`--bare`](https://code.claude.com/docs/en/headless) skips MCP server discovery, and Anthropic has said it will become the default for `-p` in a future release. Pass `--mcp-config .mcp.json` explicitly if you want the job to survive that change.
+
+See [Ingest meetings](../workflows/meeting-ingestion.mdx#automatically-on-a-schedule) for a worked example.
+
## Claude Desktop chat
`ok init` and the consent dialog also register the MCP server with Claude Desktop when it's installed — user-level, in `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Claude Desktop picks up the entry only after you quit and relaunch it.
diff --git a/docs/content/integrations/codex.mdx b/docs/content/integrations/codex.mdx
index ddaffccdc..e3030c827 100644
--- a/docs/content/integrations/codex.mdx
+++ b/docs/content/integrations/codex.mdx
@@ -23,3 +23,9 @@ Open the project in Codex and ask:
<VerifyExec />
If you don't see the tool, restart Codex. If it's still missing and `ok init` reported your config was `left unchanged`, the reason in parentheses says why `~/.codex/config.toml` (or `$CODEX_HOME/config.toml` if set) was left untouched. For config problems, fix the file and re-run `ok init`; for `no format-preserving writer available`, your config isn't the problem — OpenKnowledge can't rewrite the file safely on this platform, so add an `open-knowledge` entry to `mcp_servers` by hand (command: `ok mcp`).
+
+## Scheduled runs
+
+The ChatGPT desktop app runs Codex on a schedule from its **Scheduled** view. Tasks run unattended under your default sandbox, against your local project or an isolated background worktree, and the app must be running for tasks that need local files. See OpenAI's [scheduled tasks](https://learn.chatgpt.com/docs/automations) docs. Codex CLI has no scheduler of its own; use [`codex exec`](https://learn.chatgpt.com/docs/non-interactive-mode) from OS cron instead. Described as of August 2026, while the ChatGPT and Codex surfaces are still changing quickly.
+
+The meeting-sync prompt in [Ingest meetings](../workflows/meeting-ingestion.mdx#automatically-on-a-schedule) works verbatim as a scheduled task.
diff --git a/docs/content/workflows/meeting-ingestion.mdx b/docs/content/workflows/meeting-ingestion.mdx
index f080a78bd..69a15fe71 100644
--- a/docs/content/workflows/meeting-ingestion.mdx
+++ b/docs/content/workflows/meeting-ingestion.mdx
@@ -11,7 +11,7 @@ Meetings live in a `meetings/` folder. Any project can have one. The [Entity vau
There are two ways to get meetings in:
- **On demand.** You ask, the agent writes. Works in any editor, no extra infrastructure.
-- **Automatically.** A scheduler or a webhook asks for you, so meetings appear on their own. Needs the [OpenClaw](../integrations/openclaw.mdx) gateway.
+- **Automatically.** A schedule or a webhook asks for you, so meetings appear on their own. Schedules run from your agent's own scheduler (Claude Code, Codex) or the [OpenClaw](../integrations/openclaw.mdx) gateway; webhooks route through the gateway.
Both write the same doc, into the same folder, using the same addressing rule below.
@@ -59,7 +59,15 @@ Otter, Avoma, Teams (MS Graph), and Google Meet expose an API but no official MC
## Automatically, on a schedule
-The [OpenClaw](../integrations/openclaw.mdx) gateway has a built-in scheduler. Register both MCP servers with it, `open-knowledge` via `ok init` and your recorder's MCP per the vendor's install guide, then create one cron job that wakes an agent to run the on-demand flow for you:
+Schedule the on-demand flow in whatever scheduler your agent already has. This prompt works verbatim in any of them:
+
+```text
+Pull meetings from the recorder MCP since the last run. Write each new one into the meetings/ folder of this project, addressed as meetings/<source>-<source_meeting_id> so re-runs update in place. Do not duplicate meetings already present.
+```
+
+- **Claude Code.** Three tiers, from a local desktop task to a cloud routine that runs with your machine off. Each reaches a different set of files and MCP servers: [Scheduled runs](../integrations/claude-code.mdx#scheduled-runs).
+- **Codex.** The ChatGPT desktop app schedules it; Codex CLI runs it from OS cron: [Scheduled runs](../integrations/codex.mdx#scheduled-runs).
+- **[OpenClaw](../integrations/openclaw.mdx).** The gateway has a built-in scheduler. Register both MCP servers with it, `open-knowledge` via `ok init` and your recorder's MCP per the vendor's install guide, then create one cron job that wakes an agent with the prompt above:
```bash
openclaw cron create "*/30 * * * *" \
@@ -69,7 +77,7 @@ openclaw cron create "*/30 * * * *" \
--no-deliver
```
-Polling works for every recorder, including Granola, which has no native webhook. The gateway must be running for schedules to fire.
+Polling works for every recorder, including Granola, which has no native webhook. Schedules fire only while their host is running: the OpenClaw gateway, or the Claude / ChatGPT desktop app. Claude cloud routines are the exception, running on Anthropic's infrastructure with your machine off.
## Automatically, on an event