Querulantenkind/obsidian-promptfire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: comprehensive README update with all features

Browse source 
- Add badges and centered headings
- Document all features: multi-LLM targets, templates, history,
  section selection, frontmatter presets, context sources
- Add detailed settings documentation
- Add advanced usage section with truncation strategies
- Add quick start guide

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Luca G. Oelfke 2026-02-06 10:53:36 +01:00
parent 66b1ac8ffa
commit d61ce3a5dd
No known key found for this signature in database
GPG key ID: E22BABF67200F864
1 changed files with 387 additions and 160 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

547
README.md
View file

@ -5,33 +5,59 @@
[![Obsidian](https://img.shields.io/badge/Obsidian-Plugin-7C3AED?logo=obsidian&logoColor=white)](https://obsidian.md) [![Obsidian](https://img.shields.io/badge/Obsidian-Plugin-7C3AED?logo=obsidian&logoColor=white)](https://obsidian.md)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/Version-1.0.0-blue.svg)](package.json)
**Copy your vault context to clipboard with one hotkey.** **The ultimate context management plugin for AI-powered Obsidian workflows.**
Give AI assistants (Claude, ChatGPT, etc.) instant understanding of your vault's conventions, structure, and workflows. Copy your vault's conventions, structure, and content to any LLM with a single hotkey.
Supports Claude, GPT-4, Gemini, and any other AI assistant.
[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Configuration](#configuration) • [Generator](#context-generator) [Features](#features) • [Installation](#installation) • [Quick Start](#quick-start) • [Documentation](#documentation)
---
<img src="https://img.shields.io/badge/Multi--LLM-Support-FF6B6B?style=for-the-badge" alt="Multi-LLM Support" />
<img src="https://img.shields.io/badge/Smart-Truncation-4ECDC4?style=for-the-badge" alt="Smart Truncation" />
<img src="https://img.shields.io/badge/Template-System-45B7D1?style=for-the-badge" alt="Template System" />
<img src="https://img.shields.io/badge/Version-History-96CEB4?style=for-the-badge" alt="Version History" />
</div> </div>
--- ---
<div align="center">
## The Problem ## The Problem
When working with AI assistants on your Obsidian vault, you constantly need to explain: </div>
- How you name files
- Where things go
- What link style you use
- Your tag conventions
- Your workflows
This is repetitive and error-prone. The AI forgets, you forget to mention something, and inconsistencies creep in. When working with AI assistants on your Obsidian vault, you constantly need to explain:
- How you organize files and folders
- What link style you use (wikilinks vs markdown)
- Your tag conventions and hierarchy
- Your frontmatter requirements
- Your workflows and processes
**This is repetitive, error-prone, and wastes tokens.** The AI forgets context between sessions, you forget to mention something, and inconsistencies creep in.
--- ---
<div align="center">
## The Solution ## The Solution
**Claude Context** stores your vault's conventions in a dedicated folder (`_claude/`) and copies everything to your clipboard with a single hotkey. Paste it into any AI chat, and the assistant immediately understands how to work with your vault. </div>
**Claude Context** is a comprehensive context management system that:
1. **Stores your vault's conventions** in a dedicated folder
2. **Copies everything** to clipboard with one hotkey
3. **Adapts output** for different LLMs (Claude, GPT-4, Gemini, etc.)
4. **Tracks history** of generated contexts
5. **Supports templates** for common prompt patterns
Paste the context into any AI chat, and the assistant immediately understands your vault.
--- ---
@ -41,41 +67,185 @@ This is repetitive and error-prone. The AI forgets, you forget to mention someth
</div> </div>
### 📋 One-Click Context Copy ### One-Click Context Copy
Press a hotkey or click the ribbon icon to copy all context files to your clipboard. The output is formatted with clear separators between files. Press a hotkey or click the ribbon icon to copy all context files to clipboard. Output is formatted with clear separators and optional filename headers.
### ⚙️ Context Generator ```markdown
# === VAULT.md ===
Don't want to write context files manually? The built-in generator walks you through your preferences: Your vault conventions here...
- **Language** - English or German ---
- **File naming** - kebab-case, snake_case, camelCase, or free
- **Link style** - Wikilinks or Markdown
- **Tag style** - Hierarchical, flat, or none
- **Frontmatter fields** - Customize required fields
- **Custom rules** - Add your own conventions
- **Folder purposes** - Auto-detects your folders, you describe their purpose
- **Templates** - Define your note templates
Click "Generate" and your context files are created instantly. # === structure.md ===
### 📁 Auto-Detect Vault Structure Your folder structure here...
```
The generator automatically scans your vault's folder structure. Just fill in the purpose for each folder, and `structure.md` is generated with your actual directories. ---
### 🔧 Flexible Settings ### Multi-LLM Output Targets
- **Context folder** - Change from `_claude/` to any name <div align="center">
- **Separator** - Customize the separator between files
- **Include filenames** - Toggle `# === filename.md ===` headers
- **Show preview** - Preview before copying
- **Include active note** - Append the currently open note
- **Excluded files** - Skip specific files from being copied
### 📝 Include Active Note | Target | Tokens | Format | Strategy |
|--------|--------|--------|----------|
| **Claude** | 200,000 | XML | Summarize headers |
| **GPT-4o** | 128,000 | Markdown | Summarize headers |
| **Compact** | 8,000 | Plain | Drop sections |
Working on a specific note and want context for it? Use "Copy context with current note" or enable "Include active note" in settings. The current note is appended to your context with an `ACTIVE:` prefix. </div>
Configure multiple output targets with different:
- **Token limits** - Automatic truncation to fit context windows
- **Formats** - XML (best for Claude), Markdown, or Plain text
- **Truncation strategies** - Smart prioritization keeps important content
- **Wrappers** - Add `<context>...</context>` tags for structured prompts
**Primary target** goes to clipboard. **Secondary targets** are saved as files.
---
### Prompt Templates
Create reusable prompt templates that wrap around your context:
```markdown
You are a code reviewer. Analyze the following context and provide feedback.
{{context}}
Focus on:
- Code quality
- Best practices
- Potential bugs
{{#if activeNote}}
The user is currently working on: {{activeNote}}
{{/if}}
```
**Available placeholders:**
- `{{context}}` - The generated context
- `{{activeNote}}` - Currently open note name
- `{{activeNotePath}}` - Full path to active note
- `{{date}}` - Current date (YYYY-MM-DD)
- `{{time}}` - Current time (HH:MM)
- `{{vaultName}}` - Your vault's name
**Conditionals:** `{{#if variable}}...{{else}}...{{/if}}`
---
### Additional Context Sources
Extend your context with content from outside the vault:
| Source Type | Description | Example |
|-------------|-------------|---------|
| **Freetext** | Custom text snippets | Project-specific instructions |
| **External File** | Files outside the vault | `~/.config/rules.md` |
| **Shell Command** | Command output | `git log --oneline -10` |
Sources can be positioned as **prefix** (before vault content) or **suffix** (after).
```
# === PREFIX: Project Notes ===
Custom context here...
---
# === VAULT.md ===
Vault content...
---
# === SUFFIX: git log ===
abc1234 feat: add new feature
def5678 fix: resolve bug
...
```
---
### Granular Section Selection
Don't need the entire file? Select specific sections:
- Expand files to see their heading structure
- Check/uncheck individual sections
- See token counts per section
- Reference syntax: `NoteName#Heading` or `NoteName^blockid`
Perfect for large context files where you only need specific parts.
---
### Context History
Track every context you generate:
- **Automatic saving** with timestamps
- **Search and filter** past contexts
- **Diff comparison** between versions
- **One-click restore** to clipboard
- **Configurable retention** (max entries, auto-cleanup)
Never lose track of what context you sent to which conversation.
---
### Frontmatter Presets
Define context configuration directly in your notes:
```yaml
---
ai-context:
template: "code-review"
include-linked: true
link-depth: 2
include-tags:
- project/current
exclude-paths:
- archive/
max-tokens: 50000
---
```
Then use **"Copy context from frontmatter preset"** - the plugin automatically:
1. Reads the preset configuration
2. Traverses linked notes (up to specified depth)
3. Collects notes with matching tags
4. Applies exclusions
5. Fits within token budget
6. Applies the specified template
**One hotkey, perfectly configured context.**
---
### Context Generator
Don't want to write context files manually? The generator walks you through:
<div align="center">
| Section | Options |
|---------|---------|
| **Language** | English, German |
| **File Naming** | kebab-case, snake_case, camelCase, free |
| **Link Style** | Wikilinks `[[note]]` or Markdown `[note](path)` |
| **Tag Style** | Hierarchical `#area/tag`, Flat `#tag`, None |
| **Frontmatter** | Required fields for all notes |
| **Rules** | Custom conventions and forbidden actions |
| **Structure** | Auto-detected folders with purpose descriptions |
| **Templates** | Note templates with target folders |
</div>
Click **"Generate"** and your context files are created instantly.
--- ---
@ -85,186 +255,229 @@ Working on a specific note and want context for it? Use "Copy context with curre
</div> </div>
### From Community Plugins (Recommended)
1. Open **Settings > Community Plugins**
2. Click **Browse** and search for "Claude Context"
3. Click **Install**, then **Enable**
### From Source ### From Source
1. Clone this repository into your vault's plugins folder: ```bash
```bash # Clone into your vault's plugins folder
cd /path/to/vault/.obsidian/plugins cd /path/to/vault/.obsidian/plugins
git clone https://github.com/yourusername/obsidian-claude-context.git claude-context git clone https://github.com/yourusername/obsidian-claude-context.git claude-context
```
2. Install dependencies and build: # Install and build
```bash cd claude-context
cd claude-context npm install
npm install npm run build
npm run build
```
3. Enable the plugin in Obsidian: # Enable in Obsidian Settings > Community Plugins
- Settings → Community Plugins → Enable "Claude Context" ```
### Development Setup ### Development
For development with hot reload:
```bash ```bash
cd /path/to/vault/.obsidian/plugins/claude-context npm run dev # Watch mode with hot reload
npm run dev
``` ```
--- ---
<div align="center"> <div align="center">
## Usage ## Quick Start
</div> </div>
### Quick Start ### 1. Generate Context Files
1. **Generate context files**: `Ctrl+P` → "Claude Context: Generate context files" ```
2. **Configure your preferences** in the generator modal Ctrl+P > "Claude Context: Generate context files"
3. **Click "Generate"** to create your context files ```
4. **Copy context**: `Ctrl+P` → "Claude Context: Copy context to clipboard"
5. **Paste** into ChatGPT, Claude, or any AI assistant Configure your preferences and click **Generate**.
### 2. Add Built-in Targets
Go to **Settings > Claude Context > Output Targets** and click **"Add Built-in Targets"**.
### 3. Copy Context
```
Ctrl+P > "Claude Context: Copy context to clipboard"
```
Or click the clipboard ribbon icon.
### 4. Paste into AI Chat
The context is now in your clipboard. Paste it into Claude, ChatGPT, or any AI assistant.
---
<div align="center">
## Documentation
</div>
### Commands ### Commands
| Command | Description | | Command | Description |
|---------|-------------| |---------|-------------|
| Copy context to clipboard | Copies all context files | | **Copy context to clipboard** | Copy all context files |
| Copy context with current note | Copies context + active note | | **Copy context with current note** | Copy context + active note |
| Generate context files | Opens the context generator | | **Copy context (select sections)** | Choose specific headings |
| **Copy context from frontmatter preset** | Use note's ai-context config |
### Ribbon Icon | **Generate context files** | Open the generator |
| **View context history** | Browse past contexts |
Click the clipboard icon in the left sidebar for quick access to "Copy context to clipboard".
---
<div align="center">
## Configuration
</div>
### Settings ### Settings
Access via Settings → Claude Context: | Setting | Description | Default |
|---------|-------------|---------|
| **Context folder** | Folder with context files | `_claude` |
| **Separator** | Text between files | `---` |
| **Include filenames** | Add `# === file.md ===` headers | On |
| **Show preview** | Preview before copying | Off |
| **Include active note** | Always append current note | Off |
| **Excluded files** | Files to skip | - |
### Context Sources
| Setting | Description |
|---------|-------------|
| **Freetext** | Static text snippets |
| **External File** | Absolute path to file outside vault |
| **Shell Command** | Command + args with timeout |
| **Position** | Prefix (before) or Suffix (after) vault content |
| **Show labels** | Add source name headers to output |
### Prompt Templates
| Setting | Description |
|---------|-------------|
| **Name** | Display name |
| **Content** | Template with placeholders |
| **Default** | Use automatically when copying |
### History
| Setting | Description | Default | | Setting | Description | Default |
|---------|-------------|---------| |---------|-------------|---------|
| Context folder | Folder containing context files | `_claude` | | **Enabled** | Save generated contexts | On |
| Separator | Text between files | `---` | | **Storage folder** | Where to store history | `.context-history` |
| Include filenames | Add filename headers | On | | **Max entries** | Limit stored entries | 50 |
| Show preview | Preview before copying | Off | | **Auto-cleanup** | Delete after X days | 30 |
| Include active note | Always include open note | Off |
| Excluded files | Files to skip (comma-separated) | Empty |
### Context Files ### Output Targets
The plugin expects markdown files in your context folder: | Setting | Description |
|---------|-------------|
``` | **Name** | Display name (e.g., "Claude", "GPT-4") |
_claude/ | **Max tokens** | Token limit for truncation |
├── VAULT.md # Main entry point (always first) | **Format** | markdown, xml, or plain |
├── conventions.md # Naming and formatting rules | **Strategy** | summarize-headers, drop-sections, truncate |
├── structure.md # Folder organization | **Wrapper** | Prefix/suffix text around content |
├── workflows.md # How to do things | **Primary** | Which target goes to clipboard |
├── templates.md # Note templates | **Output folder** | Where to save secondary targets |
└── examples.md # Concrete examples
```
`VAULT.md` is always copied first. Other files are sorted alphabetically.
--- ---
<div align="center"> <div align="center">
## Context Generator ## Advanced Usage
</div> </div>
The generator creates a complete context setup based on your preferences. ### Truncation Strategies
### Sections When content exceeds token limits:
**General** | Strategy | Behavior |
- Vault description (free text explaining your vault's purpose) |----------|----------|
- Language selection | **summarize-headers** | Keep headers, summarize content. Best for structure preservation. |
| **drop-sections** | Remove low-priority sections entirely. Keeps high-priority complete. |
| **truncate** | Simple cut-off. Fast but loses structure. |
**Formatting** ### Priority Order
- File naming convention
- Link style (Wikilinks vs Markdown)
- Maximum heading depth
- Date format
**Tags** Sections are prioritized for truncation:
- Tag style (hierarchical, flat, or none)
- Predefined tags for consistency
**Frontmatter** 1. **VAULT.md** - Never truncated (highest priority)
- Required fields for all notes 2. **context** files - High priority
3. **conventions** - High priority
4. **structure** - Medium priority
5. **Active note** - Medium priority
6. **examples, templates** - Low priority (truncated first)
**Rules** ### Frontmatter Preset Options
- Custom rules for the AI to follow
- Forbidden actions (folders/files the AI should never touch)
**Folder Structure** ```yaml
- Auto-detected folders with purpose fields ai-context:
- Generates "where does what go" documentation # Apply a saved template by name
template: "code-review"
**Note Templates** # Include linked notes
- Define template names, target folders, and tags include-linked: true
- Generates template documentation link-depth: 2 # How deep to traverse (0-10)
**Files to Generate** # Include notes with these tags
- Toggle which context files to create include-tags:
- Skip files you don't need - project/myproject
- status/active
# Exclude paths
exclude-paths:
- archive/
- templates/
# Exclude notes with these tags
exclude-tags:
- draft
- private
# Token budget
max-tokens: 50000
# Include the note itself
include-active-note: true
```
### XML Format (Claude Optimized)
When using XML format, files are wrapped in tags:
```xml
<context>
<file name="VAULT.md">
Your vault conventions here...
</file>
<file name="structure.md">
Your folder structure here...
</file>
</context>
```
This format is especially effective with Claude models.
--- ---
<div align="center"> <div align="center">
## Example Output ## Contributing
</div> </div>
When you copy context, you get something like: Contributions are welcome! Please:
```markdown 1. Fork the repository
# === VAULT.md === 2. Create a feature branch
3. Make your changes
# Vault Context for AI Assistants 4. Run `npm run build` to verify
5. Submit a pull request
Personal Zettelkasten for development and knowledge management.
## Quick Reference
- Language: English
- File naming: kebab-case
- Links: [[wikilinks]]
- Frontmatter: `date`, `tags`
...
---
# === conventions.md ===
# Conventions
## Language
- Vault language: English
...
---
# === structure.md ===
...
```
Paste this into any AI chat, and it immediately understands your vault.
--- ---
@ -280,6 +493,20 @@ MIT License - see [LICENSE](LICENSE) for details.
<div align="center"> <div align="center">
Made with ♥ for the Obsidian community ## Support
</div>
- **Bug reports:** [GitHub Issues](https://github.com/yourusername/obsidian-claude-context/issues)
- **Feature requests:** [GitHub Discussions](https://github.com/yourusername/obsidian-claude-context/discussions)
- **Documentation:** [Wiki](https://github.com/yourusername/obsidian-claude-context/wiki)
---
<div align="center">
**Made with care for the Obsidian community**
If this plugin helps your AI workflow, consider starring the repository!
</div> </div>