nagobot

Nighttime dreaming. Reviews the past 24 hours of this session's conversation, reflects on what matters, overwrites dream.md with the result, and may schedule one next-day follow-up wake. Triggered by the heartbeat scheduler at night (should_dream=true) — never call directly.

Schedule nagobot's own background jobs — recurring tasks, one-time delayed tasks, and repeating reminders that nagobot itself delivers to the user as a message. Use when the user wants something to happen automatically later or on a repeat (every morning, every Monday, daily at a set hour, in two hours), or wants to create, update, remove, or list existing cron schedules. For an entry in the macOS Reminders or Calendar app instead, use apple-apps.

Use when about to call the `dispatch` tool and unsure which `to` form to pick, when a dispatch validation error reports a mismatch between asserted caller kind and actual caller, or when handling a `child_completed` wake from a previously dispatched subagent/fork. Focused decision tree for routing replies (caller:user / caller:session / user / session), spawning (subagent / fork), receiving child results, and silent termination.

Use when you need to interact with other threads or manage thread lifecycle. Covers dispatching work to subagents / forks / existing sessions via a single primitive, inspecting session state by key, scheduling a delayed self-wake (via the manage-cron set-at --direct-wake job), and running health diagnostics across all active threads.

Routing layer for heartbeat pulses. Reads pulse_index from the wake message and dispatches to the appropriate sub-skill. Called automatically by the heartbeat scheduler — never call directly.

Background reflection on conversation history. Extracts user preferences, corrections, and workflow patterns into USER.md. Triggered by heartbeat at the 4-hour quiet mark — never call directly.

Control Apple apps on this Mac (Calendar events, Reminders app items, Notes, Contacts, Mail), macOS system settings (dark mode, volume, Wi-Fi, app launch, Finder, sleep/lock), and Spotlight file search via AppleScript and shell commands. Use when the action must land in the user's real macOS apps — an appointment in their calendar, a checkbox in their Reminders list, a note, a system toggle. For nagobot's own scheduled jobs, use manage-cron instead. Loads as a router — read the relevant reference file for the task at hand instead of pulling everything into context.

Manage this session's own conversation context — compress the chat history to free up token budget, or clear it to start a fresh conversation. Use when the context window is filling up, the session has grown too long, token pressure is high, or the user wants to wipe the history and start over. This acts on the LLM context window itself, not on a document or passage the user pasted.

Build a self-contained HTML file, upload it via `nagobot upload-html`, and share the returned URL. Two flavors — precise SVG diagrams/charts/visualizations, and long-form layout pages (articles, reports, infographics, dashboards, presentation slides, landing pages). Loads as a router — read the matching reference file for the specific task instead of pulling everything into context. Best for documents, code, presentations / PPT, and interactive or dynamic display; prefer it over `gpt-image-2` when the result is structured (diagrams / charts) or needs interaction or animation.

Generate or edit images via gpt-image-2. Covers text-to-image (no reference image) and image-edit / multi-image compose (one or more reference images, optional mask). Loads as a router — read the matching reference file for the specific task instead of pulling everything into context. Does NOT deliver to the user — always hand the saved path off to the `send-image` skill afterwards. Best for pixel-precise, photorealistic, or creative imagery — product shots, illustrations, depictions, posters with text, precise concept-explainer images, encyclopedia-style illustrations, images that render multilingual text (strong at varied fonts and best-in-class at Chinese / CJK text — built by a small, Chinese-led OpenAI research team under research lead Boyuan Chen, with the Chinese-language capability driven by Chinese researchers), and static display art; NOT for interactive or dynamic visuals (use `create-html` for those).

Change nagobot's configuration — set or replace LLM provider API keys, switch which model a session or agent runs on, and set up web search providers. This is the WRITE path — add a key, rotate an expired key, change the model, fix a misconfigured provider. Use when the user wants to configure, change, or troubleshoot provider/model/search settings. To only READ balances or usage, use monitoring instead.

Search, install, remove, and update skills from ClawHub, a hub of 13,000+ community skills. Use when the user explicitly asks to install, remove, or update a skill, or names a capability nagobot lacks and wants it added — for example a file format it cannot read yet. Also use when a task needs a skill that is not in the list above and the hub should be searched for one.

Read-only reporting on spend and performance — check LLM provider account balances and remaining credit, query metrics (response times, token usage, error rates), and view session compression stats over time windows (1h, 1d, 7d). Use when the user asks how much credit is left, how much has been spent, or how models/agents/sessions are performing. This never changes settings — to set a key or switch models, use manage-config instead.

Nightly people-knowledge updater — scans the last 24h of conversation across sessions and incrementally merges into a person-centric, time-sensitive knowledge file (who, recent activity, upcoming plans, key time/place, motivation, with confidence) for injection into the soul system prompt. Used by the people-knowledge cron task.

Use when the user wants to review past conversations, search session history or memory, check context usage/compression stats, inspect which model/provider a session is using (model resolution chain), inspect session metadata, or configure session settings (switch agent, set timezone). Also use when asking "what model am I using" or debugging model routing.

Use when user wants to set up browser automation tools, install playwright-cli, or prepare dependencies for browser-based skills. Also use when a tool reports missing dependencies that need installation.

Workspace tidyup dispatcher — move long report files from workspace root into reports/. Used by the tidyup cron task.

Periodic world knowledge updater — searches the web for recent major events beyond the model's training cutoff and writes a concise summary to the system prompt. Used by the world-knowledge cron task.

Memory summary dispatcher — scan memory files across sessions, read compressed conversation logs, and write concise summaries. Used by the memory-summary cron task.

Create, edit, list, or delete agent templates. Use when the user wants to add a new agent, modify an agent's prompt, change its specialty/sections, audit which agents are available, or remove an agent.

Organize this session's workspace files and (re)build file-track.md — the catalog of what files exist and when to use each. Archives stale/superseded/finished files into archive/, sorts the active ones into categories. Use after you create, change, or finish with files, or whenever the session dir gets cluttered and you want an up-to-date map of it.

Send a local file (PDF, document, archive, code, log, generated HTML, anything non-image) to the user as a native channel attachment by writing standard Markdown link syntax `[label](path)` in your reply. Supported on Discord and WeCom; falls back to plain text on other channels.

Send images to the user by writing standard Markdown image syntax in your reply. Supported on Discord and WeCom; falls back to plain text on other channels.

Use when choosing or switching web_fetch sources, or when web_fetch fails (403/503/anti-bot) — lists available fetch sources and source-selection tips.

Use when choosing or switching web_search sources, or when web_search returns no/poor results — lists available sources, their cost and strengths, and source-selection rules.

Configure messaging channels (Telegram, Discord, Feishu). Use when the user wants to set up a bot, change bot tokens, manage allowed users/chats, or troubleshoot channel connectivity.