Skip to main content

Flows

One job, end to end

One job traced through the services it touches. Back to Services, or on to Plugins to write your own.

A flow is one job, from something happened to it was handled: a recording becomes a transcript, a receipt becomes a budget entry.

Turning one on​

Each flow is a file in automation/plugins/flows/: the services it needs, the automations it turns on, and any step only you can do. What you have on is one list, workspace/.decree/plugins.yml.

./existential.sh flow                 # pick from the list; ✓ marks the ones on
./existential.sh flow on weekly-newsletter   # asks for each service it needs, into plugins.yml, then a rebuild installs it
./existential.sh flow off weekly-newsletter  # out of plugins.yml; services stay as they are
  • docker compose up -d afterwards starts anything new.
  • A flow that needs another turns that one on too.
  • off never deletes a file you changed.
  • worker and auto-update run on the host itself, in a decree daemon there (host/.decree), not in a container. ./existential.sh says so until one runs.
FlowWhat it doesNeeds, beyond Core
you-were-hereEvery morning, yesterday in one notification. On by defaulta chat model
look-backThe week and the month in review, next to your notes. On by defaulta chat model
clean-runsPrunes decree's finished run logs after a week. On by default—
health-checksProbes a service every 15 minutes, and tells your phone when it stops. On by default—
note-to-automationWrite "next time X, do Y" in a note, accept what is proposed, and it runs. On by defaulta chat model
capture-streamWhat you type to an agent, and anything you POST, in one stream in workspace/.capture/. On by default—
code-server-agentsclaude, opencode and pi in code-server's terminal, pi on your own model. On by default—
weekly-newsletterYour own newsletter from only the feeds you pickeda chat model
check-versionsMondays, the services with a newer image—
searchYour notes, PDFs and Word files, by meaning and by words (qmd)qmd
gmail-inboxNew mail every 15 minutes, as decree messages (Gmail)a Google grant
budgetBank alerts become budget entriesActual Budget, gmail
note-triageThe note you meant to come back toNextcloud, a chat model
note-connectNotes that find their own connectionssearch
nextcloud-captureA file uploaded through Nextcloud runs the file processorsNextcloud, automation-webhook
image-ocrA photo's text, written beside itnextcloud-capture, a vision model
transcriptionRecordings become speaker-labelled transcriptsWhisperX, nextcloud-capture
workspace-agentA file matching your criteria is handed to an agentqmd, Firecrawl, nextcloud-capture
notes-to-dropboxNextcloud notes compiled and pushed to Dropboxnextcloud-capture, a Dropbox remote
calendarNextcloud's calendar, every event mirrored into the workspaceNextcloud
office-documentsWord, Excel and PowerPoint in the browserNextcloud, Collabora
local-modelsOllama on this host pulls your tier's models, onceOllama
home-voiceTalk to the house: Home Assistant, speech in and out, your chat model answeringHome Assistant, Wyoming
photosImmich, its admin made and your NAS photos indexed read-onlyImmich
comfyuiComfyUI workflows a decree message runsComfyUI and its models
workerThis host, reported to your controller: disks, automations, runs, in Grafanadecree on the host
auto-updateFollow the branch: git pull, ./existential.sh, docker compose up -d every 15 minutesdecree on the host

Note → Automation is part of Core, on whenever a chat model answers.

Housekeeping​

  • clean-runs prunes workspace/.decree/runs/ (logs also go to Loki when it's on).
  • health-checks probes ntfy. For another service, copy its cron in workspace/.decree/cron/ to health-check-<slug>.md and set SERVICE_NAME and SERVICE_URL (http://<container>:<port>/<health path>).
  • check-versions reports images that are behind. ./existential.sh run check-versions --update patches the templates; then ./existential.sh && docker compose pull && docker compose up -d.

How every flow works​

Every flow has four parts:

  input  →  judgment  →  work  →  output
  1. Input. A file, an email, your voice, a webhook, a schedule. Each becomes a message in one queue.
  2. Judgment. One cheap question: is this worth acting on? Most things aren't.
  3. Work. The expensive part, only for what passed: transcribe, research, extract, draft, file.
  4. Output. A note, a task, a budget line, a notification, or another message.
Don't skip judgment

Without it, the expensive step runs on everything and you get a folder of unread reports.

The four knobs​

The four parts are what you change, and three are settings, not code:

KnobWhat it isHow you change it
InputWhat triggers the flowPick a trigger: a cron file, a webhook endpoint, a file-processor PATTERN, an inbox drop
JudgmentWhat counts as worth acting onOne line of prompt in cron frontmatter — e.g. TRIAGE_CRITERIA
WorkWhat actually gets doneThe name of the machine to chain — e.g. TRIAGE_ROUTINE
OutputWhere the result landsA destination setting, or the machine you chained

Each knob changes independently. Note → Action walks through all four. A new flow is one more plugin: Writing a Plugin.

By kind​

Capture​

Voice​

Money​

Building your own​

Every flow is a plugin with no machine, needing the plugins that do the work.