From d61ce3a5dd788fd22d23dfb555d2c726bdded11c Mon Sep 17 00:00:00 2001 From: "Luca G. Oelfke" Date: Fri, 6 Feb 2026 10:53:36 +0100 Subject: [PATCH] docs: comprehensive README update with all features - 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 --- README.md | 547 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 387 insertions(+), 160 deletions(-) diff --git a/README.md b/README.md index 8c15ae3..5736095 100644 --- a/README.md +++ b/README.md @@ -5,33 +5,59 @@ [![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/) [![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) + +--- + +Multi-LLM Support +Smart Truncation +Template System +Version History --- +
+ ## The Problem -When working with AI assistants on your Obsidian vault, you constantly need to explain: -- 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. --- +
+ ## 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. +
+ +**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 -### 📋 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 -- **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. +
+ +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 `...` 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: + +
+ +| 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 | + +
+ +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 +### From Community Plugins (Recommended) + +1. Open **Settings > Community Plugins** +2. Click **Browse** and search for "Claude Context" +3. Click **Install**, then **Enable** + ### From Source -1. Clone this repository into your vault's plugins folder: - ```bash - cd /path/to/vault/.obsidian/plugins - git clone https://github.com/yourusername/obsidian-claude-context.git claude-context - ``` +```bash +# Clone into your vault's plugins folder +cd /path/to/vault/.obsidian/plugins +git clone https://github.com/yourusername/obsidian-claude-context.git claude-context -2. Install dependencies and build: - ```bash - cd claude-context - npm install - npm run build - ``` +# Install and build +cd claude-context +npm install +npm run build -3. Enable the plugin in Obsidian: - - Settings → Community Plugins → Enable "Claude Context" +# Enable in Obsidian Settings > Community Plugins +``` -### Development Setup - -For development with hot reload: +### Development ```bash -cd /path/to/vault/.obsidian/plugins/claude-context -npm run dev +npm run dev # Watch mode with hot reload ``` ---
-## Usage +## Quick Start
-### 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 -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 +``` +Ctrl+P > "Claude Context: Generate context files" +``` + +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. + +--- + +
+ +## Documentation + +
### Commands | Command | Description | |---------|-------------| -| Copy context to clipboard | Copies all context files | -| Copy context with current note | Copies context + active note | -| Generate context files | Opens the context generator | - -### Ribbon Icon - -Click the clipboard icon in the left sidebar for quick access to "Copy context to clipboard". - ---- - -
- -## Configuration - -
+| **Copy context to clipboard** | Copy all context files | +| **Copy context with current note** | Copy context + active note | +| **Copy context (select sections)** | Choose specific headings | +| **Copy context from frontmatter preset** | Use note's ai-context config | +| **Generate context files** | Open the generator | +| **View context history** | Browse past contexts | ### 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 | |---------|-------------|---------| -| Context folder | Folder containing context files | `_claude` | -| Separator | Text between files | `---` | -| Include filenames | Add filename headers | On | -| Show preview | Preview before copying | Off | -| Include active note | Always include open note | Off | -| Excluded files | Files to skip (comma-separated) | Empty | +| **Enabled** | Save generated contexts | On | +| **Storage folder** | Where to store history | `.context-history` | +| **Max entries** | Limit stored entries | 50 | +| **Auto-cleanup** | Delete after X days | 30 | -### Context Files +### Output Targets -The plugin expects markdown files in your context folder: - -``` -_claude/ -├── VAULT.md # Main entry point (always first) -├── conventions.md # Naming and formatting rules -├── structure.md # Folder organization -├── workflows.md # How to do things -├── templates.md # Note templates -└── examples.md # Concrete examples -``` - -`VAULT.md` is always copied first. Other files are sorted alphabetically. +| Setting | Description | +|---------|-------------| +| **Name** | Display name (e.g., "Claude", "GPT-4") | +| **Max tokens** | Token limit for truncation | +| **Format** | markdown, xml, or plain | +| **Strategy** | summarize-headers, drop-sections, truncate | +| **Wrapper** | Prefix/suffix text around content | +| **Primary** | Which target goes to clipboard | +| **Output folder** | Where to save secondary targets | ---
-## Context Generator +## Advanced Usage
-The generator creates a complete context setup based on your preferences. +### Truncation Strategies -### Sections +When content exceeds token limits: -**General** -- Vault description (free text explaining your vault's purpose) -- Language selection +| Strategy | Behavior | +|----------|----------| +| **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** -- File naming convention -- Link style (Wikilinks vs Markdown) -- Maximum heading depth -- Date format +### Priority Order -**Tags** -- Tag style (hierarchical, flat, or none) -- Predefined tags for consistency +Sections are prioritized for truncation: -**Frontmatter** -- Required fields for all notes +1. **VAULT.md** - Never truncated (highest priority) +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** -- Custom rules for the AI to follow -- Forbidden actions (folders/files the AI should never touch) +### Frontmatter Preset Options -**Folder Structure** -- Auto-detected folders with purpose fields -- Generates "where does what go" documentation +```yaml +ai-context: + # Apply a saved template by name + template: "code-review" -**Note Templates** -- Define template names, target folders, and tags -- Generates template documentation + # Include linked notes + include-linked: true + link-depth: 2 # How deep to traverse (0-10) -**Files to Generate** -- Toggle which context files to create -- Skip files you don't need + # Include notes with these tags + include-tags: + - 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 + + +Your vault conventions here... + + + +Your folder structure here... + + +``` + +This format is especially effective with Claude models. ---
-## Example Output +## Contributing
-When you copy context, you get something like: +Contributions are welcome! Please: -```markdown -# === VAULT.md === - -# Vault Context for AI Assistants - -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. +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Run `npm run build` to verify +5. Submit a pull request --- @@ -280,6 +493,20 @@ MIT License - see [LICENSE](LICENSE) for details.
-Made with ♥ for the Obsidian community +## Support + +
+ +- **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) + +--- + +
+ +**Made with care for the Obsidian community** + +If this plugin helps your AI workflow, consider starring the repository!