Obsidian Agent Blocks

Render local LLM output directly inside notes using an agent Markdown code block.

Features

• Runs automatically when the note is rendered.
• Reusable agent templates with provider-specific configuration.
• Multiple providers:
  • Codex CLI
  • Ollama (local)
• Loading state and one-click refresh per block.
• Stop button on running blocks and running execution log entries.
• Execution log in settings with:
  • timestamp
  • origin note
  • provider/template
  • duration
  • full prompt
  • full response
  • command line args
  • streamed stdout/stderr output
  • in-flight status
• Prompt cache with configurable max size (default: 1000 entries).
• Standardized prompt wrapper with Obsidian context:
  • vault root path
  • current file path
  • current note content
  • optionally selected linked note content
• Template-configurable context sources (currently linked note content).
• Per-block context source overrides (enable/disable, sizing, filtering, and sorting).
• Global instructions applied to every run.
• Per-block provider overrides (for example model, reasoning, temperature, timeout, mcp, local provider).
• Template and per-block cache mode:
  • auto-refresh (default)
  • prefer-cache (uses last cached result for that block until manual refresh)

Requirements

• Desktop Obsidian (isDesktopOnly: true).
• For Codex templates: local codex CLI installed.
• For Ollama templates: local Ollama server and a pulled model.

Block usage

Inline instruction (uses default agent template)

```agent
Summarize this note into 5 action items.
```

linked_content_sort_by supports:

• modified-date (default)
• created-date
• frontmatter-date

linked_content_sort_direction supports:

• descending (default)
• ascending

Template reference

```agent
template: weekly-summary
Focus on blockers and decisions.
```

Codex overrides in a block

```agent
template: codex-default
model: gpt-5-mini
reasoning: low
mcp: false
timeout: 120
oss: true
local_provider: ollama
Summarize only unresolved items.
```

Ollama overrides in a block

```agent
template: local-ollama
model: llama3.2
temperature: 0.1
num_predict: 700
host: http://127.0.0.1:11434
Summarize this file.
```

Context source overrides in a block

```agent
template: fast-summary
linked_content: true
linked_content_max_notes: 6
linked_content_max_chars: 1500
linked_content_sort_by: frontmatter-date
linked_content_sort_direction: descending
linked_content_sort_frontmatter_date_field: review_date
linked_content_include_outgoing: true
linked_content_include_backlinks: false
linked_content_filter_required_frontmatter_field: review_date
Summarize this note and key linked context.
```

Cache mode override in a block

```agent
template: deep-analysis
cache_mode: prefer-cache
Run a thorough analysis using linked context.
```

When cache_mode: prefer-cache is active, prompt changes do not auto-run. The block reuses the last cached result for that block and marks it as stale until you click refresh.

Codex local model setting

For Codex templates, you can enable:

• Use local OSS provider (adds --oss)
• Local provider (adds --local-provider, e.g. ollama, lmstudio, ollama-chat)

This lets Codex route to a local provider while keeping Codex prompt/tooling behavior.

Architecture

This project is split into layers so behavior is easier to change safely.

Folder map

• src/main.ts
  • Plugin entrypoint and composition root.
  • Wires services and registers the agent code block processor.
• src/domain/
  • Shared domain model and rules.
  • types.ts: canonical plugin types.
  • defaults.ts: default config values and template factory helpers.
  • normalizers.ts: clamping/normalization logic used across layers.
  • template-utils.ts: template conversion/duplication helpers.
• src/core/
  • Application services and stateful orchestration.
  • settings-normalization.ts: load and normalize persisted settings.
  • agent-runner.ts: provider execution + cancellation lifecycle.
  • execution-log-service.ts: execution log lifecycle and streamed output formatting.
  • prompt-cache.ts: prompt cache pruning policies.
  • process-output.ts: stdout/stderr stream formatting and truncation.
• src/agent-block/
  • Runtime pipeline for ```agent blocks rendered in notes.
  • directives.ts: parse top-of-block directives and produce an execution request.
  • context.ts: gather note/link context.
  • prompt.ts: build standardized wrapped prompt.
  • cache.ts: deterministic cache keys.
  • render.ts: render model response/error into the block.
  • dependencies.ts: runtime contract expected from plugin services.
  • safe-dependencies.ts: wrappers for non-critical dependency calls that should not break rendering.
• src/ui/
  • Settings UI code.
  • ui/settings/agent-setting-tab.ts: settings tab composition and controls.
  • ui/settings/execution-log.ts: execution log display widgets.
• src/providers/
  • Provider adapters (codex-provider.ts, ollama-provider.ts) and provider interface (types.ts).

Dependency direction

Keep imports flowing in this direction:

• ui, agent-block, core, and providers can import from domain.
• main.ts can import from every layer (composition root).
• domain should not import from ui, core, or agent-block.
• providers should not import settings UI modules.
• ui should not own business rules; it should call shared domain/core helpers.

Agent block execution flow

1. Obsidian renders an agent code block and calls registerAgentCodeBlockProcessor.
2. agent-block/directives.ts parses directives and resolves template + overrides.
3. agent-block/context.ts gathers current note + linked note context.
4. agent-block/prompt.ts builds standardized prompt text.
5. agent-block/cache.ts computes cache keys and checks cached responses.
6. core/agent-runner.ts executes the selected provider (providers/*).
7. core/execution-log-service.ts records invocation/output lifecycle.
8. agent-block/render.ts renders final markdown response (or error) into the note.

Adding new code (rules of thumb)

• Add or change shared data shape/rules in domain.
• Add orchestration/stateful process logic in core.
• Add note-render runtime behavior in agent-block.
• Add settings UX only in ui.
• Keep main.ts small and focused on wiring.

Development

npm install
npm run dev

Build:

npm run build