obsidian-promptfire/README.md

<div align="center">

# Claude Context

[![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)

**The ultimate context management plugin for AI-powered Obsidian 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) • [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

</div>

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

</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.

---

<div align="center">

## Features

</div>

### One-Click Context Copy

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.

```markdown
# === VAULT.md ===

Your vault conventions here...

---

# === structure.md ===

Your folder structure here...
```

---

### Multi-LLM Output Targets

<div align="center">

| Target | Tokens | Format | Strategy |
|--------|--------|--------|----------|
| **Claude** | 200,000 | XML | Summarize headers |
| **GPT-4o** | 128,000 | Markdown | Summarize headers |
| **Compact** | 8,000 | Plain | Drop sections |

</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.

---

<div align="center">

## Installation

</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

```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

# Install and build
cd claude-context
npm install
npm run build

# Enable in Obsidian Settings > Community Plugins
```

### Development

```bash
npm run dev  # Watch mode with hot reload
```

---

<div align="center">

## Quick Start

</div>

### 1. Generate Context Files

```
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** | 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

| 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 |
|---------|-------------|---------|
| **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 |

### Output Targets

| 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">

## Advanced Usage

</div>

### Truncation Strategies

When content exceeds token limits:

| 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. |

### Priority Order

Sections are prioritized for truncation:

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)

### Frontmatter Preset Options

```yaml
ai-context:
  # Apply a saved template by name
  template: "code-review"

  # Include linked notes
  include-linked: true
  link-depth: 2  # How deep to traverse (0-10)

  # 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">

## Contributing

</div>

Contributions are welcome! Please:

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

---

<div align="center">

## License

</div>

MIT License - see [LICENSE](LICENSE) for details.

---

<div align="center">

## 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>