Skip to content

Automations and routines

SecondBrain integrates recurring automations (similar in spirit to scheduled/API agent “routines”): you define a prompt and schedule once, then run from the CLI, sb serve, or external HTTP/GitHub hooks.

Two automation kinds

Kind CLI Effect
Session automations sb sessions automations … Launches background agent sessions (native / Claude / Codex), optional workflow + task seeding.
Workflow automations sb workflow automations … Materializes project tasks from the prompt on each tick.

AI workforces build on the same machinery. sb workforce deploy <id> creates or updates a session automation that can launch a declarative team of role-backed background sessions, starting with the local-only portfolio_scouts workforce.

Integration-backed jobs remain under sb automations (separate subsystem).

Shared automation core

brain/automations/ now provides the common primitives used to keep the automation lanes aligned:

  • schedules.py owns interval:<seconds> and cron:<5-field-crontab> parsing, validation, and next-run calculation for local automation stores.
  • policies.py owns concurrency and execution-mode decisions (skip, queue, replace; emit_decision vs run_only).
  • engine.py keeps the lightweight embedded automation runner, with typed Python handlers and explicitly injected LLM handlers for offline-safe code-plus-model automations.
  • blueprints.py can turn a natural-language automation goal into a runtime recommendation and step plan. It uses deterministic local heuristics by default, and can use an injected LLM provider when a caller wants model-backed planning.

Higher-level stores still own durable writes: workflow automations materialize tasks, session automations launch durable agent sessions, and integration automations run governed connector sync jobs.

Sleep-time lane

Session automations now also support a governed sleep-time lane for background reflection and memory improvement:

sb sessions automations create "Nightly Memory Pass" \
  --prompt "Review recent history and propose durable memory updates" \
  --schedule "interval:1800" \
  --sleep-time

This does not write durable memory directly. The sleep-time pass runs as a normal durable background session, emits checkpoints for reflection and memory consolidation, and places proposed durable-memory updates into the review queue for approval.

Schedules

Both kinds accept:

  • interval:<seconds> — e.g. interval:3600
  • cron:<5-field crontab> — UTC, e.g. cron:0 9 * * 1-5

sb serve APIs

With authentication (SB_SERVE_TOKEN / serve_auth.json):

  • GET/POST /session-automations, POST /session-automations/{id}/run, …
  • GET/POST /workflow-automations, POST /workflow-automations/{id}/run, …
  • POST …/run-due on both (bulk; requires global serve auth)

Optional trigger message

POST …/{id}/run JSON body may include message — appended to the task description (workflow) or merged into the session goal (session).

Per-automation invoke tokens

For automation-specific triggers (deploy hooks, internal tools) without sharing the global token:

  1. Create with generate_invoke_token: true (API) or --generate-invoke-token (CLI), or call POST …/rotate-invoke-token.
  2. Call POST …/{id}/run with header X-SB-Automation-Invoke: <token> (global Bearer still works).

Rotate: POST …/rotate-invoke-token. Revoke narrow access: DELETE …/invoke-token.

GitHub webhooks

Set SB_GITHUB_WEBHOOK_SECRET in the environment where sb serve runs (same value as GitHub’s webhook secret).

Register GitHub to POST:

  • /webhooks/github/session-automations/{automation_id}
  • /webhooks/github/workflow-automations/{automation_id}

Only pull_request events are acted on; the payload is summarized into the session goal or task context. Ping events return 200 with ignored: ping.

Unified CLI entry

sb routines guide prints this map of commands and endpoints.

Operations UI

The local Operations page in serve-ui lists session and workflow automations for monitoring.

See also