obsidian-promptfire/AGENTS.md

Promptfire – Obsidian Plugin

Project overview

An Obsidian community plugin that manages and copies vault context to clipboard for use with LLMs. Stores conventions, structure, and rules in a dedicated folder and provides one-hotkey copy with multi-LLM output formatting, prompt templates, frontmatter presets, granular section selection, and context history.

• Entry point: src/main.ts → compiled to main.js via esbuild
• Release artifacts: main.js, manifest.json, styles.css (optional)
• Plugin ID: promptfire
• Desktop only: true (uses Node.js fs and child_process for external sources)

Environment & tooling

• Runtime: Obsidian (Electron/Chromium)
• Language: TypeScript (strict: true)
• Package manager: npm
• Bundler: esbuild (config in esbuild.config.mjs)
• Target: ES2018, CommonJS output
• Dependencies: only obsidian (latest) – no external runtime deps

Commands

npm install          # Install dependencies
npm run dev          # Watch mode (incremental, inline sourcemaps)
npm run build        # Type-check + production build (minified, no sourcemaps)

Testing

Manual only – copy main.js, manifest.json, styles.css to <Vault>/.obsidian/plugins/promptfire/, reload Obsidian, enable plugin.

Source file structure

src/
├── main.ts                # Plugin class, command registration, core copy logic
├── settings.ts            # PromptfireSettings interface, defaults, settings tab UI
├── generator.ts           # Context generator modal (vault structure setup wizard)
├── sources.ts             # External context sources (freetext, file, folder, shell)
├── source-modal.ts        # Modal for adding/editing context sources
├── presets.ts             # Frontmatter preset parser & executor (ai-context block)
├── targets.ts             # Multi-target output system (format, truncation, token limits)
├── target-modal.ts        # Modal for adding/editing output targets
├── templates.ts           # Prompt template engine & 5 starter templates
├── template-modal.ts      # Modal for adding/editing templates + import/export
├── history.ts             # Context history manager (save, cleanup, versioning)
├── history-modal.ts       # History viewer modal (browse, diff, restore)
├── content-selector.ts    # Heading/block tree parser for granular selection
├── file-selector-modal.ts # Modal for selecting files and sections
├── preview.ts             # Preview modal before copying

Plugin commands

ID	Name	Description
copy-context	Copy context to clipboard	Main command – copies all context files + sources
copy-context-with-note	Copy context with current note	Same as above but always includes active note
copy-context-selective	Copy context (select sections)	Opens file/heading selector modal
copy-context-from-preset	Copy context from frontmatter preset	Reads ai-context YAML block from active note
generate-context	Generate context files	Opens setup wizard to create initial context folder
view-history	View context history	Opens history browser with diff and restore

Ribbon icon: clipboard-copy → triggers copy-context.

Settings (PromptfireSettings)

Setting	Type	Default	Description
contextFolder	string	'_context'	Vault folder containing context .md files
separator	string	'---'	Text separator between files in output
includeFilenames	boolean	true	Add # === filename === headers
showPreview	boolean	false	Show preview modal before copying
includeActiveNote	boolean	false	Always append the currently open note
excludedFiles	string[]	[]	Filenames to skip (case-insensitive)
sources	ContextSource[]	[]	External context sources
showSourceLabels	boolean	true	Add position/name labels to source output
promptTemplates	PromptTemplate[]	[]	Prompt templates with placeholders
defaultTemplateId	string | null	null	Template applied automatically on copy
history	HistorySettings	see below	History configuration
targets	OutputTarget[]	[]	Multi-LLM output targets
primaryTargetId	string | null	null	Target that goes to clipboard
targetOutputFolder	string	'_context/outputs'	Folder for secondary target files

History settings

Setting	Type	Default
enabled	boolean	false
storageFolder	string	'.context-history'
maxEntries	number	50
autoCleanupDays	number	30

Architecture & key modules

Context sources (sources.ts)

Four source types, each with position: 'prefix' | 'suffix':

Type	Config	Notes
freetext	{ content: string }	Inline text snippets
file	{ path: string }	External file (absolute path, requires Node.js fs)
folder	{ path: string; recursive: boolean; pattern?: string }	Directory with optional glob filter
shell	{ command: string; args: string[]; cwd?: string; timeout?: number }	Command output (default timeout 5s, max 1MB)

Output targets (targets.ts)

Three built-in targets (can add custom):

Name	Tokens	Format	Strategy
Promptfire	200,000	xml	summarize-headers
GPT-4o	128,000	markdown	summarize-headers
Compact (8k)	8,000	plain	drop-sections

Formats: markdown (default), xml (wraps in <file name="..."> tags), plain (strips markdown).

Truncation strategies: truncate (hard cut), summarize-headers (keep headers, collapse content), drop-sections (remove low-priority sections entirely).

Priority order for truncation: VAULT.md > context files > conventions > structure > active note > examples/templates.

Prompt templates (templates.ts)

Handlebars-like engine with variables: {{context}}, {{selection}}, {{active_note}}, {{active_note_name}}, {{date}}, {{time}}, {{datetime}}, {{vault_name}}. Supports {{#if var}}...{{else}}...{{/if}} conditionals.

Five starter templates: Code Review, Summary, Q&A, Continue Writing, Explain.

Frontmatter presets (presets.ts)

Reads ai-context YAML block from the active note's frontmatter:

ai-context:
  template: "Template Name"
  include-linked: true
  link-depth: 2          # 0-10
  include-tags: [tag1]
  exclude-paths: [archive/]
  exclude-tags: [draft]
  max-tokens: 50000
  include-active-note: true

Features: hierarchical tag matching, link traversal with cycle detection, token budgeting, full validation with errors/warnings.

Content selector (content-selector.ts)

Parses heading tree (H1–H6) and block IDs (^blockid) from markdown files. Enables partial file selection via FileSelectorModal. Output marks partial files with (partial) suffix.

History (history.ts)

Stores each generated context as JSON in vault. Tracks metadata: template used, included files/sources, active note, char/token counts, user notes. Auto-cleanup by age and entry count.

Coding conventions

• main.ts handles plugin lifecycle and command registration – all feature logic lives in dedicated modules.
• Each module exports its types/interfaces alongside implementation.
• Modals are in separate *-modal.ts files, business logic in the corresponding .ts file.
• Settings are persisted via loadData()/saveData() with Object.assign merge pattern.
• VAULT.md is always sorted first in context output.
• Token estimation: chars / 4 (rough approximation).
• No external runtime dependencies – everything bundled into main.js.
• CSS class prefix: pf- (e.g. pf-settings-tabs, pf-gen-modal).

Obsidian plugin conventions

• Add commands with stable IDs – never rename after release.
• Use this.register* helpers for cleanup on unload.
• No network calls without explicit user opt-in and documentation.
• No telemetry, no remote code execution.
• Keep minAppVersion accurate (0.15.0 currently).
• Bump version in manifest.json (SemVer), update versions.json, create GitHub release (tag = version, no v prefix).

Manifest (manifest.json)

{
  "id": "promptfire",
  "name": "Promptfire",
  "version": "1.0.0",
  "minAppVersion": "0.15.0",
  "description": "Copy vault context files to clipboard with one hotkey for any LLM.",
  "author": "Luca",
  "isDesktopOnly": true
}