Vault Crews

by Johannes Kaindl
5
4
3
2
1
Score: 54/100

Description

Run autonomous local LLM agent teams (crews) on your vault via LM Studio

Reviews

No reviews yet.

Stats

1
stars
529
downloads
0
forks
130
days
4
days
4
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
388
commits

Latest Version

4 days ago

Changelog

Added

  • text.append output family: the model writes text that is appended to the target note (note.append), under an optional heading (written without #). max_chars defaults to 4000 and may be at most 16000 (the same upper bound as section.write). Appending is not repeatable: a second run appends again.
  • {{input}} as target of an actions task: with per_note: true on the llm task it is the path of the note each call is about, so every note gets its own section or text. Without per_note: true the crew is rejected at parse time.
  • per_note: true on an llm task: one model call per note of its inputs, one after the other, each call sees only that note. At most 20 notes per task (the rest is skipped and named in run.md, the run ends partial); on_error: skip skips the one note, on_error: abort stops the run; a note read in part or not fitting the context alone is named per note; the panel shows "Note 3 of 7". Raw answers of such a task are kept as artifacts/<taskId>-n<index>-<attempt>.txt. max_writes has to be raised (plugin setting first) for batches above the default of 10, otherwise the actions task fails with write_limit. Set per_note: true for large batches: without it, notes beyond the total limit of 262 144 characters stand in the material without content ([gekürzt]) but stay writable, so the model can write to or move a note whose text it never saw.
  • values and add_to on frontmatter.set: a field gets a set of allowed values from list, from: tags (the tags of the vault) or from: notes with a folder (written as [[Name]]), at most 300 values per field (run.md names the cut), and add_to adds to the note's list (union without duplicates, built when the note is written) instead of replacing it. add_to compares exactly: tags: "a, b" as one text becomes ONE element. A tag that does not exist in the vault is rejected.
  • notes.create output family and note.create from a model: new notes in a fixed folder (may contain {{today}}), with fixed frontmatter and an optional link to the processed note (link_source, path link, needs per_note: true); only title (at most 120 characters, at least one letter or digit) and text come from the model; max_items defaults to 5, at most 50. A taken path is never overwritten; "exists" and a duplicate title in one run do not count towards the consistency threshold, so a repeated run ends partial. No promise of repeatability: other titles in a second run make more notes. A fixed folder is checked against write_scope and the denylist when the crew file is read ({{today}} is probed with 2000-01-01, so write_scope needs a pattern like Journal/**).
  • note.file output family and the note.move action: the model files notes into a list of folders (destinations with an optional when, and/or destinations_from, up to 100 subfolders) or answers none. Source and target are checked against write_scope and the denylist, the target folder must exist (never created), a taken target path is rejected. note.move must be in the last task of the crew, at most one task. Obsidian updates the links in other notes when it moves a note, as set in its settings, which changes notes outside write_scope. Undo moves the note back; if it is no longer at the new path or the old path is taken again, it is left alone and reported as a conflict. Old snapshots stay readable.
  • review field in the team file: required as review: false as soon as a crew allows note.create, note.append or note.move; review: true is rejected ("Vorschau kommt mit dem nächsten Release") because the preview is not built yet. Crews that allow none of these actions stay valid without the field; see “Changed” for the crews that do not.
  • Example crew "Sort inbox" (German: "Eingangsordner einsortieren"): reads up to 8 notes of an inbox folder, adds tags from the tags the vault already has (add_to: [tags]) and moves each note into one of two example folders. It points at Inbox, Projects, Archive (German Inbox, Projekte, Archiv); the text says to adjust the three folders before the first run. Files: teams/sort-inbox.md, agents/inbox-sorter.md (German teams/eingang-einsortieren.md, agents/eingang-sortierer.md).

Changed

  • Breaking for hand-written crews from 0.26 that allow note.create or note.append: the parser now requires review: false in the team file for them (without it the crew is rejected as crew_invalid); 0.26 accepted both actions without the field. The shipped crews are not affected. Add review: false to such a crew.

  • The persona of the example crew "Sort inbox" has max_tokens: 4096 (was 1536; German eingang-sortierer). A model that thinks despite thinking: off (google/gemma-4-e4b) ran into the limit in 3 of 10 runs in the tagging step; with 4096, 10 of 10 runs finished, 20 of 20 answers valid without repair, 80 of 80 notes in the right folder. Needs a context window above about 4800 tokens (8192 recommended) (the prompt budget is context minus max_tokens minus 15 %).

  • A crew with note.move is refused up front when Obsidian does not update links on moves. With Settings → Files & Links → “Automatically update internal links” off, Obsidian shows an “Update links” dialog in the middle of the move and the run waits for a click (a trigger: interval run would hang and hold the single-run lock for good). The preflight now refuses such a crew with the new error kind links_not_followed and names the setting, before the lock, the snapshot or any model call. The setting is off by default in Obsidian, so it has to be switched on for crews with note.move; a setting that cannot be read counts as off (the crew is refused). The refusal sentence, the README and the description of the example crew “Sort inbox” say so.

  • section.write through an output: block prompts neutrally ("the finished section", example ## Zusammenfassung) instead of with the briefing wording. output_schema: briefing-v1 keeps its wording and example byte for byte.

  • Two actions tasks that both allow section.replace with the same target are rejected at parse time (they would overwrite the same section); the comparison ignores case and path spelling (Notes/X.md against notes/x.md), also two times {{input}}.

  • heading of text.append is written without #; a heading with a leading # is rejected at parse time.

  • max_writes counts notes, not actions: each note that is changed, created or moved counts once per run; two steps on the same note count once, a move of an already counted note adds nothing.

  • The staleness guard accepts the run's own last state of a note, so a crew can set frontmatter and then write a section on the same note. Any other change stays "stale".

  • The run id carries seconds and counts up when taken (YYYY-MM-DD-HHMMSS-<crew>, then -2, -3). Older run folders stay readable.

  • vault.read over 262 144 characters of total content now returns the remaining notes as files whose content is [gekürzt] instead of leaving them out; before, they were missing without a trace.

  • "Undo did not finish" text: a failed undo no longer claims that nothing was changed (earlier moves may have run); the run stays undoable and a second attempt skips what is already restored.

  • Prompt budget: the token estimate comes from the library's model-context (characters of system and user estimated once, not rounded twice); the budget cut is at most one entry more generous than before, never tighter. The 15 % reserve stays. Library update to obsidian-kit 0.92.0 and code-kit 0.73.0.

README file from

Github

Vault Crews

Run autonomous local LLM agent teams ("crews") on your Obsidian vault, powered by a local LLM model (LM Studio or Ollama) — with a deterministic, orchestrator-led pipeline and a snapshot safety net under every run.

Local models are treated as weak, unreliable executors. The orchestrator decides flow, paths and writes; the model only ever decides content, inside narrow, schema-validated contracts. Every output is constrained, then verified, before it ever touches your vault.

License: AGPL-3.0 Docs: CC BY-SA 4.0 Release Obsidian

🇬🇧 English · 🇩🇪 Deutsch

Features

  • Deterministic pipeline, not a free-form agent loop. A crew ("team") is a sequence of exactly three task kinds — collector (deterministic context gathering), llm (one chat completion against a schema-validated contract), and actions (deterministic application of a validated action list to the vault). The model never controls flow and never touches the vault directly.
  • Constrain-then-verify before every write. Every LLM output is extracted, schema-validated against a built-in, versioned schema, and source-bound — a model cannot invent a file path or an enum value that didn't already exist in the collected material. A repair pass (one retry) handles malformed JSON.
  • Git-free snapshot undo, one click. Before a run touches a note, its pre-run state is snapshotted (copy-on-write) into a hidden store via the Obsidian vault/adapter API. "Undo last run" restores changed notes from the snapshot and moves run-created notes to the trash — no git repository required, works in any vault.
  • Five shipped example crews, installable via a command, in the language of the Obsidian interface (English or German): Task triage (reviews backlog TaskNotes, proposes metadata corrections on soft fields only), Daily briefing (summarizes open tasks into today's daily note), Note tagger (proposes tags for notes that have none) and Maturity tagger (estimates a note's maturity from its content and writes it to the frontmatter) and Sort inbox (adds existing tags to the notes of an inbox folder and moves each into a matching folder). They point at the neutral folders Tasks, Daily, Notes and Inbox with the targets Projects and Archive (German: Aufgaben, Tagesnotizen, Notizen, Inbox, Projekte, Archiv); each team's text says to adjust them before the first run.
  • Full observability, in the vault. Every run writes a human-readable run.md (frontmatter + per-task detail, Bases-compatible) and a machine-readable state.json, plus a shipped runs.base dashboard.
  • Crash recovery. An orphaned lock + a state.json still marked running are detected on the next plugin load, with one recommended action: finish the run (keep the partial changes — they remain undoable via the write-ahead snapshot).
  • English/German UI.

Requirements

  • Desktop only (isDesktopOnly: true — the plugin is built around a locally-hosted LLM served over HTTP, a desktop workflow).
  • A local LLM server: LM Studio (default port 1234) or Ollama (default port 11434), serving an OpenAI-compatible API. The endpoint is configurable in the plugin settings; just enter the URL (e.g., http://localhost:1234/v1 for LM Studio or http://localhost:11434/v1 for Ollama). You can list several endpoints (one per line), and the plugin uses the first reachable one at each preflight. No provider selection needed — the plugin auto-detects context length and capabilities.
  • Enable CORS on your LLM server. The plugin streams model output via XMLHttpRequest from inside Obsidian's renderer process (requestUrl cannot stream). LM Studio: Settings → Developer → Enable CORS. Ollama: set the environment variable OLLAMA_ORIGINS=<your-obsidian-app-url> (optional; without it, the plugin falls back to non-streaming mode, and results still arrive).
  • No git repository required. The undo net is a per-run snapshot taken via the Obsidian vault/adapter API, so it works in any vault — git repo or not. (Earlier versions required a git repo; as of 0.2.0 that requirement is gone.)

Live token streaming needs CORS enabled on your LLM server. The ticker runs as an XMLHttpRequest from Obsidian's renderer, which always sends Origin: app://obsidian.md. LM Studio rejects that preflight unless the server was started with --cors (lms server start --cors), Ollama unless OLLAMA_ORIGINS allows it. Without it the run still completes — the plugin falls back to a non-streaming request through Obsidian's main process — but the panel shows „Waiting for output…" until the task is done.

Install

Canonical repository: git.jkaindl.de/jkaindl/vault-crews, mirrored on GitHub where the releases are published.

Via AnySource Sideloader, which installs and updates plugins from any git forge. Subscribe to the plugin catalog once under Settings → AnySource Sideloader → Catalogs → Add:

https://git.jkaindl.de/jkaindl/obsidian-catalog/raw/branch/main/catalog.json

Vault Crews then appears in the sideloader's plugin list and updates like any other plugin; every download is checksum-verified. To install just this one plugin without the catalog, add its repository URL as a source instead: https://github.com/johannes-kaindl/vault-crews.

Manual

Download main.js, manifest.json and styles.css from the latest release into <vault>/.obsidian/plugins/vault-crews/, then enable the plugin under Settings → Community plugins. Each release also ships checksums.sha256, so you can verify what you downloaded with shasum -a 256 -c checksums.sha256.

cp main.js manifest.json styles.css "<your-vault>/.obsidian/plugins/vault-crews/"

From source

git clone https://git.jkaindl.de/jkaindl/vault-crews
cd vault-crews
npm install
npm run build   # produces main.js

Copy main.js, manifest.json and styles.css into <vault>/.obsidian/plugins/vault-crews/.

After enabling (whichever route), run the command "Install example crews" to seed _crews/ (default root, configurable in settings) with the five example teams (Task triage, Daily briefing, Note tagger, Maturity tagger, Sort inbox; German interface: Task-Triage, Daily-Briefing, Notiz-Tagger, Reifegrad-Tagger, Eingangsordner einsortieren), their agents, and the runs.base dashboard. Installed files are never overwritten by a second run — edit them freely afterwards.

Usage

  1. Start your local LLM server (LM Studio or Ollama) with CORS enabled, and load a model. The plugin resolves the first reachable endpoint at each preflight.
  2. Run "Install example crews" once — it seeds the crew root (_crews by default) with the five example teams, their agents, and the runs.base dashboard.
  3. Open the crews panel (ribbon icon or Open crews panel). It lists the teams it found and, during a run, the current task with live token counts.
    • The panel has two tabs, Crews and History. Click one, or focus the tab bar and use the Left/Right arrow keys (Home/End jump to the first/last tab). During a run, the status line with the one Cancel button stays at the bottom, whichever tab is open.
  4. Start a run with Run crew… and pick a team, or use the per-team command Run crew: <name> that every team registers under its own name.
  5. Watch it work. The panel shows each task's status (waiting, running, ok, failed, skipped, stale). Abort current run requests a stop, observed between tasks and inside the model stream.
  6. Read the log. Every run writes run.md (human-readable, Bases-compatible) and state.json next to it; Open last run log jumps there, and runs.base lists all runs at once.
  7. Undo if needed. Undo last run shows what it would restore (team, time, files) and asks before doing it — changed notes are restored from the snapshot, run-created notes go to the trash.

Writing your own teams and agents is plain Markdown in the vault — see Writing your own crews below.

Configuration

Settings → Community plugins → Vault Crews, in four groups:

Setting Default Meaning
Endpoints http://localhost:1234/v1 One row per endpoint, each with its own URL, optional API key (kept in Obsidian's secret storage, not in data.json) and model; the first reachable one is used per run. Check connections probes each row and reports refused / unknown host / timeout / not-an-LLM-API / access denied separately
Denied endpoints localhost:8080, 127.0.0.1:8080 Never contacted — the default keeps the plugin off a port other local model servers commonly claim. A setting, not hardcoded
Request (profile) What a run sends with each model call: sampling values (temperature, top_p, top_k, …) and the thinking level, from a profile table per model family and backend. Collapsed section; shows what is sent and what has an effect on your backend, takes your own values per model family, lists the last request and any deviations seen this session. Values in an agent note override it for that agent. The row "Level picker in chat" has no effect in Vault Crews
Crew root folder _crews Vault-relative folder holding agents, teams and run logs
Hide crew folder in the file explorer off Purely cosmetic: the crew root disappears from the explorer, its notes stay in the vault
Max writes per run 10 Plugin-wide cap; a team's own max_writes can only be lower. 0 stops all crews from writing
Wall-clock limit 10 minutes Aborts a runaway run, leaving its partial writes snapshotted and undoable. At least 1
Undo history depth 15 At least 1. How many run snapshots of the current day are kept. Older days thin out: one snapshot per day for a week, then per week (4 weeks) and per month (6 months), none after that
Call timeout 300 s Hard limit per model call — generous, because just-in-time model loading takes a while. At least 10 s
Stall timeout 60 s Aborts if no new token arrives; only checked after the first data chunk, so loading is never mistaken for a stall. At least 5 s
Record every model call off Writes each model call of a run (full request body, raw response, reasoning, duration, status; never request headers, and API keys are redacted) as one line to <crew root>/runs/<run>/calls.jsonl.gz, packed when the run ends. For finding out why a model answered the way it did. Run folders are never cleaned up, so every run adds one such file, and the recording copies the text of the notes sent to the model into your vault; leave it off unless you are debugging

If the LLM Endpoint Manager plugin is installed, the endpoint (and its API key and model) comes from there and the settings show the manager's picker instead of the list above; without it, the list above is used as before.

Endpoint and timeout changes take effect with the next run; no plugin reload is needed.

How it works

A run is an orchestrator walking a fixed pipeline, not a model deciding what to do next. Each team is a sequence of exactly three kinds of task:

  1. collector — deterministic gathering. Code, not the model, reads the vault and assembles the material (e.g. tasknotes.query over a folder, optionally with note content).
  2. llm — exactly one chat completion, answering against a schema declared by the task's output: block. The model sees only the collected material and produces only content — never a path, never a flow decision.
  3. actions — deterministic application. The validated action list is applied to the vault by code.

Between the model and your notes sit two independent checks. Stage 1 (output-validator) parses the raw response, validates it against a built-in versioned schema, and binds every path and enum value back to the material actually collected — a path the model invented has nothing to bind to and is rejected. One repair attempt handles malformed JSON. Stage 2 (action-executor) re-checks each action immediately before the write, independently of stage 1: against the write_scope allowlist and the fixed denylist, the allowed action types and frontmatter keys, and a content hash — if you edited the file after it was collected, that action is skipped rather than overwriting your edit. If more than half of a task's actions fall away, the task fails instead of applying a half-consistent state.

Writes are snapshotted write-ahead: a note's pre-run content is copied into a hidden per-run store through the Obsidian vault/adapter API before it is touched. That is why even a crashed or aborted run stays fully undoable, and why no git repository is needed.

Safety model

  • write_scope whitelist, per team, plus a fixed denylist that always wins. Every team declares the vault-relative globs it may write to. A fixed denylist — .obsidian/**, .git/**, _crews/**, _vaultrag/**, dotfiles — overrides any whitelist unconditionally; crews can never read or write their own configuration (no self-triggering, no prompt-injection path into plugin control).
  • A snapshot under every write — one-click undo. Before each note is written, its pre-run content is captured write-ahead into a hidden per-run store (under .obsidian/plugins/vault-crews/undo/). Even a failed or aborted run with partial writes stays fully undoable. Undo last run restores changed notes and trashes run-created ones, showing exactly what it will undo (team, time, files) before you confirm — and warns if a note was edited after the run rather than silently overwriting it. Run-created notes go to the Obsidian trash, never a hard delete.
  • Write and wall-clock limits. max_writes per run (team-configurable, capped by a plugin-wide maximum), a hard per-note size cap, an LLM call budget, and a wall-clock watchdog (default 10 minutes) that aborts a runaway run (leaving its partial writes snapshotted and undoable) rather than running forever.
  • Consistency threshold. If more than 50% of a task's proposed actions are rejected or stale, the whole task fails instead of applying a semantically inconsistent partial state; below that threshold, individual actions are skipped and logged.
  • Constrain-then-verify, twice. Stage 1 (output-validator) validates the raw model JSON against a built-in schema and binds every path/enum value to the material actually collected for that task. Stage 2 (action-executor) re-checks every action against the path whitelist/denylist, allowed action types, allowed frontmatter keys, and a content-hash staleness guard (if you edited the file since it was collected, that single action is skipped, never silently overwritten) — immediately before the write, independent of stage 1.

Network disclosure

  • The plugin talks only to the endpoints you list in its settings. Out of the box that is a local LLM server (LM Studio http://localhost:1234/v1, Ollama http://localhost:11434/v1). No other host is ever contacted, no telemetry, no analytics, no update-check pings.
  • Endpoints may carry an API key, which makes hosted, OpenAI-compatible providers usable as a fallback. Adding a key means requests — including the note content a crew collects — leave your machine for that provider. The settings row says so explicitly once a key is set, and the list is ordered: a reachable local endpoint above a hosted one is always used first. Keys live in Obsidian's secret storage (the system keychain), not in your vault: data.json keeps only a reference, so a synced vault does not carry them. A key you entered before 0.14.0 moves there the next time the plugin resolves its endpoints.
  • Secrets in your notes are masked before a model sees them. Private keys (PEM blocks), Bearer tokens and common API-key formats (sk-…, ghp_…, …) in the text a crew sends become placeholders such as [redacted-token-1]; the answer gets the original back before the crew writes it. Notes reach the model as JSON text, so a restored PEM block keeps its line breaks written as \n. E-mail addresses and other personal data are not masked.
  • Keys never reach the run logs. Everything written into your vault (run.md, state.json) and everything shown in the panel passes a redaction step first — including error bodies, which is the realistic leak path: some gateways echo the Authorization header back in a 401 response.
  • Port 8080 is denylisted by default (commonly reserved by other local single-consumer model servers) — this is a default setting, not a hardcoded behavior, and can be changed.
  • No shell execution and no direct filesystem access: the undo net writes its snapshots through the Obsidian vault/adapter API only, never child_process or node:fs.

V1 limitations

Documented rather than silently missing:

  • No mid-run transport retry / endpoint re-resolve. If LM Studio dies or the connection drops mid-stream, the current call fails and the run ends failed with its partial writes snapshotted; the plugin does not attempt to reconnect or re-resolve the endpoint within a run. This is deliberately deferred — a failed run is always safe (undo snapshot + full log) and cheap to re-run: section.replace is idempotent and note.create/patch semantics refuse to double-apply, so simply re-running the same crew after restarting LM Studio is the supported recovery path.
  • Crash recovery assumes a single device. The orphaned-run detection (stale lock
    • state.json still running) is designed for "Obsidian crashed on this machine mid-run". A vault synced across two concurrently-running Obsidian desktops (e.g. via iCloud/Syncthing while both are open) is explicitly out of scope for V1 — see design risk #8.
  • Raw LLM output on validation failure is captured under runs/<id>/artifacts/. Whenever a task's output fails schema/source-binding validation, the raw model response is written to artifacts/<taskId>-1.txt; if the one repair attempt also fails validation, its raw response is written to artifacts/<taskId>-2.txt. This feeds the test-fixture corpus of real broken model outputs and is written under the run directory — it is never counted as a vault write, never touches max_writes, and is not snapshotted for undo. Successful runs write no artifacts at all.
  • The raw text of a successful call is in the run folder only with the call log. Without the setting "Record every model call", a run writes raw answers to artifacts/ only for an invalid answer or a repair. With it, every request and answer is in calls.jsonl.gz; images do not appear in the call log, because no collector reads any.
  • The failure log opens run.md at the top, not scrolled to the failed task. "View failure" opens the run's log file via workspace.getLeaf().openFile() with no ephemeral scroll state — you land at the top of the note and scroll to the relevant ## section yourself.
  • Aborting a run is cooperative — and the panel is honest about it. "Cancel" / "Abort current run" sets the abort flag, which is observed between tasks and inside the LLM stream; when it bites you get status: aborted with partial writes (undoable). With a fast local model a whole run can finish in 1–2 s, so a click can land after the last checkpoint and the run completes normally — that is correct (the work was already done), not a lost click. The panel reflects this truthfully: while aborting it shows "Abort requested…", and if the run finished first it states "the run finished before the abort took effect — nothing was aborted" rather than freezing on a spinner. There is deliberately no mechanism to throw away already-completed work.

Writing your own crews

A crew is Markdown in the vault: a team (crew-kind: team) as a pipeline of collector → llm → actions, plus agent notes (crew-kind: agent, system prompt in the body). The crews that ship with the plugin (command "Install example crews") are editable examples — copy them and adjust.

Sharing crews: a crew is just Markdown files, so sharing is a file copy — no import or export dialog. The command "Show crew folder in the file explorer" takes you to the crew root (_crews by default) so you can copy a team file out, or drop one in. A team needs its agent notes with it: copy the team file from teams/ together with the agents it names from agents/. The command tells you if the folder is hidden by the "Hide crew folder" setting.

Model settings of an agent (temperature, seed, max_tokens, thinking)

An agent note can set four model values in its frontmatter; all are optional and override the plugin's Request settings for that agent.

temperature is sent as given; without it the profile value for the model family applies (0.1 for crews). seed is a whole number from 0 up (anything else is an error in the agent note); it is shown in the run log (- Seed: 42), but the plugin sends it only where the backend accepts it (today Open WebUI, per the kit's profile table): LM Studio ignores it (measured by the kit) and so does not get it, and the other backends are not measured and do not get it either. Then the run log says not sent, so a seed is no promise of repeatable answers there. The same holds for a seed set in the Request settings. max_tokens is the agent's token budget (default 2048); a thinking level can raise it to the model family's reserve so thinking cannot eat the whole budget. thinking is off, on or auto (default): off asks the model not to think, on asks for the medium level, auto follows the Request settings, whose default is off.

The panel shows which model and thinking level each agent of a crew gets: open Models under a crew in the Crews tab. It is read-only. A model: in the agent note is shown as a wish: it counts only if the active endpoint carries that model, otherwise the model of the endpoint row, shown next to it, is used. The panel never asks the endpoint, so it cannot say which of the two applies before a run starts. Change the fallback model in the settings opens the plugin's settings, where the endpoint row's model is set. Once a crew has run, the block also names the model each agent used in that last run (Last run: …), so you can see which of the two applied; before the first run that line is absent.

Output vocabulary (output:)

An llm task declares its output format through an output: block:

  • frontmatter.set — the model proposes frontmatter values for source notes. allowed_keys restricts which fields may be set. Paths are bound to the collected material (no hallucination); the structural enum constraint binds values to those actually present in the vault, but only takes effect once the field already has values in that folder — on the very first run (no values yet, no value table) a restriction comes from the instruction and the agent prompt alone.
    output:
      family: frontmatter.set
      allowed_keys: [tags, kategorie]
    
    With values you give a field a set of allowed values, with add_to you name the fields whose value is added to the note's list instead of replacing it (the union without duplicates, built when the note is written; without add_to the value replaces, as before). A set comes from list (fixed values), from: tags (the tags of the vault, written without #) or from: notes with a folder (the notes of that folder and its subfolders, written as [[Name]]). The model sees a short form of each value and the original is written. A value without a usable short form, or with the same short form as another, is named in run.md. At most 300 values per field: for tags the most frequent ones, for notes the most recently changed ones, and run.md names the cut. A key under values that is not in allowed_keys makes the crew invalid. A tag that does not exist in the vault is rejected. add_to compares exactly, without normalising: tags: "a, b" as one text becomes ONE element, not two tags.
    output:
      family: frontmatter.set
      allowed_keys: [type, tags, projekt]
      values:
        type: { list: [Protokoll, Rechnung, Notiz] }
        tags: { from: tags }
        projekt: { from: notes, folder: Projekte }
      add_to: [tags]
    
  • section.write — the model writes Markdown text, which section.replace puts into the target of the following actions task. Optional max_chars (default 16000).
    output:
      family: section.write
    
  • text.append — the model writes Markdown text, which note.append adds to the end of the target of the following actions task, under the heading heading if you set one (the heading must already exist in the note). Optional max_chars (default 4000, at most 16000).
    output:
      family: text.append
      heading: Log
    
    Appending is not repeatable: a second run appends again. heading is written without # (Log, not ## Log).
  • notes.create — the model proposes new notes as {"items": [{"title": "…", "body": "…"}]}; only title and text come from the model. The folder, the frontmatter fields of every new note and the field for a link to the processed note are fixed in the crew file. The path is folder, then the title run through the file-name policy, then .md; the title is at most 120 characters and needs at least one letter or digit. folder may contain {{today}}. The content is built by the library's frontmatter module, not by joining text. max_items defaults to 5 and may be at most 50, more items are a schema error. link_source names the frontmatter field that gets a link to the processed note and needs per_note: true; the link is written as a path link ([[Inbox/Note]]). The actions task needs note.create in allowed_actions. Notes that already exist are never overwritten: the action is rejected with "exists", and so is the same title twice in one run. These rejections do not count towards the consistency threshold, so a repeated run with the same titles ends partial, not failed. notes.create does not promise repeatability: if the model gives other titles in a second run, more notes appear.
    output:
      family: notes.create
      folder: Aufgaben
      max_items: 10
      frontmatter: { type: Aufgabe, status: backlog, tags: [aus-crew] }
      link_source: quelle
    
    frontmatter values are single-line text, numbers or lists of single-line text, and folder with {{today}} is checked against write_scope with the date 2000-01-01: the scope needs a pattern such as Journal/** or Journal/20*/**, not a single day.
  • note.file — the model files notes: {"items": [{"path": "…", "to": "…"}]}. path is bound to the collected material, to must be a folder from the list or none. none, and the folder the note is already in, produce no action. The list is destinations (fixed folders with an optional description when) and/or destinations_from (the direct subfolders of one folder, at most 100, without description); at least one of the two is required. A subfolder outside write_scope, on the denylist, or named none is left out and run.md says so. The actions task needs note.move in allowed_actions, there is at most one such task per crew and it must be the last task. Source and target folder must lie in write_scope; the target folder must already exist, the crew never creates a folder, and a target path that is taken is rejected. Moving goes through Obsidian's file manager, which updates links in other notes as set in the Obsidian settings. Moving needs that setting switched on (Settings → Files & Links → “Automatically update internal links”; it is off by default in Obsidian, so switch it on for crews with note.move): with it off, Obsidian asks in a dialog in the middle of the run and the run would wait for a click, so a crew with note.move in allowed_actions does not start (the run is refused with the reason, before anything is locked or written). That changes notes outside write_scope: the limit applies to the moved note, not to the links pointing to it. Undo moves the note back (and the links again); if the note is no longer at the new path or the old path is taken again, it is left alone and reported as a conflict. If such a note cannot be restored at all (it is gone, or its old path is taken), a second dialog offers to discard the run; otherwise the run stays undoable until its snapshot expires.
    output:
      family: note.file
      destinations:
        - { folder: Projekte/Meyer, when: "Everything about the customer Meyer" }
        - { folder: Archiv/Rechnungen, when: "Invoices and receipts" }
      destinations_from: Projekte
    

With per_note: true on the llm task the model is called once per note, and the target of the following actions task may be {{input}}: it stands for the path of the note that call is about, so each note gets its own section or text. {{input}} without per_note: true is a definition error. Two actions tasks that both allow section.replace must not share a target.

One model call per note (per_note). With per_note: true the llm task runs once per note of its inputs, one after the other, and each call sees only that note. The actions of all calls together are the result of the task. At most 20 notes per task: the rest is skipped, run.md names them and the run ends partial. on_error: skip skips the one note and goes on, on_error: abort stops the run. A note that was read in part (the collector caps one note at 32 768 characters and all notes together at 262 144) is marked in run.md as "read in part"; a note that does not fit the model's context alone counts as an error of that call. The wall clock applies as before: when it runs out in the middle of such a task, the run ends failed and the message names the setting. max_writes counts notes, not actions: each note that is changed, created or moved counts once per run, so a note that is tagged and then moved counts once. For batches above the default of 10, raise the plugin setting "Max writes per run" first and then max_writes in the crew file, otherwise the actions task fails with write_limit. Set per_note: true for large batches: without it, notes beyond the total limit of 262 144 characters stand in the material without content ([gekürzt]) but stay writable, so the model can write to or move a note whose text it never saw.

Several steps on the same note. The run remembers the state it wrote last for each path. The staleness guard accepts a note whose current state is either the state at collection or that last own state, so a crew can first set frontmatter and then write a section on the same note. Any other change (you type in the note while the run is going) stays "stale".

What the families do not promise

  • A step must not build on the effect of an earlier step of the same run: appending to a note that the same run creates is not supported. The write steps check against the vault as it was before the run; several steps on an existing note are fine.
  • Free text from the model (the content of new notes, sections, appended text) can contain things you did not want, for example a link, if a note it read led it there. Everything else the model chooses is structurally bound: paths come from the collected material, folders from the crew file, targets from a list, values from a value set. Check the result in run.md and use Undo.
  • Two actions tasks must not have the same target if both allow section.replace (also two times {{input}}).
  • Crews that allow note.create, note.append or note.move must say review: false in this release (see below). This also applies to hand-written crews from 0.26 that allow note.create or note.append: 0.26 accepted them without the field, now they are rejected as crew_invalid until review: false is added; the shipped crews are not affected.

Preview (review)

review: false is required in the team file as soon as a crew can create, append or move notes. review: true is rejected with "Vorschau kommt mit dem nächsten Release": the preview before writing (the waiting run) is not built yet, a crew writes right away and you check the result in run.md and use Undo. The field is required now so that the later default (true for writing crews) does not silently change a crew written in the meantime.

The older names output_schema: triage-v1 / briefing-v1 remain valid as shorthands.

Reading content (include_content)

By default tasknotes.query returns frontmatter only. For crews that need the note text (taggers, summarizers), set include_content: true:

collector: tasknotes.query
params:
  folder: Notizen
  where_missing: [tags]
  include_content: true

Write safety (write_scope)

write_scope is a glob allowlist: a crew may write there and nowhere else. Set it as narrowly as possible — and point the collector's folder and write_scope at the same folder, otherwise proposals outside the write scope are discarded. The plugin-wide limit "Max writes per run" caps every team's max_writes on top of that.

Recurring runs (trigger: interval)

A team with trigger: interval and interval: 30m (units m, h, d; at least 5m) starts by itself while Obsidian is open. The first run comes one interval after the plugin loads, never at start-up. A due run goes through the same one-run lock as a click: if another run is active, that tick is skipped silently and the next interval counts from there. Nothing is made up after Obsidian was closed. Everything that protects a manual run still applies: schema validation, write_scope, the write cap and the undo snapshot.

Documentation

License

Code: AGPL-3.0-or-later — see LICENSE for the full text. Documentation: CC BY-SA 4.0 (LICENSE-DOCS). A commercial license is available on request — see LICENSING.md.