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 <noreply@anthropic.com>
This commit is contained in:
Luca G. Oelfke
parent
66b1ac8ffa
commit
d61ce3a5dd
1 changed files with 387 additions and 160 deletions
535
README.md
535
README.md
|
|
@ -5,33 +5,59 @@
|
|||
[](https://obsidian.md)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](LICENSE)
|
||||
[](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 align="center">
|
||||
|
||||
## 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
|
||||
</div>
|
||||
|
||||
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
|
||||
|
||||
**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>
|
||||
|
||||
### 📋 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
|
||||
<div align="center">
|
||||
|
||||
### 📝 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>
|
||||
|
||||
### 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
|
||||
# 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
|
||||
# Install and build
|
||||
cd claude-context
|
||||
npm install
|
||||
npm run build
|
||||
|
||||
# Enable in Obsidian Settings > Community Plugins
|
||||
```
|
||||
|
||||
3. Enable the plugin in Obsidian:
|
||||
- Settings → Community Plugins → Enable "Claude Context"
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
## Usage
|
||||
## Quick Start
|
||||
|
||||
</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
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
## Documentation
|
||||
|
||||
</div>
|
||||
|
||||
### 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".
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
## Configuration
|
||||
|
||||
</div>
|
||||
| **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 |
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
## Context Generator
|
||||
## Advanced Usage
|
||||
|
||||
</div>
|
||||
|
||||
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
|
||||
<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">
|
||||
|
||||
## Example Output
|
||||
## Contributing
|
||||
|
||||
</div>
|
||||
|
||||
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.
|
|||
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue