bitsofchris_openaugi-obsidian-plugin/CLAUDE.md

OpenAugi Obsidian Plugin - Technical Overview

Project Purpose

OpenAugi is an Obsidian plugin that transforms voice notes and linked notes into organized, atomic notes using AI (GPT-4). It helps users process unstructured thoughts into a structured "second brain" by breaking down content into self-contained ideas.

Architecture Overview

Core Technologies

• Language: TypeScript
• Build Tool: esbuild
• Target Platform: Obsidian (Electron-based)
• AI Service: OpenAI GPT-4.1-2025-04-14
• Node Version: 18+

Project Structure

/
├── src/
│   ├── main.ts                 # Plugin entry point, command registration
│   ├── services/
│   │   ├── openai.service.ts   # AI processing logic
│   │   ├── file.service.ts     # File operations, output management
│   │   └── distill.service.ts  # Linked note extraction, content aggregation
│   ├── ui/
│   │   └── settings.ts         # Settings tab UI component
│   └── utils/
│       └── filename.utils.ts   # Filename sanitization, backlink mapping
├── manifest.json               # Obsidian plugin metadata
├── package.json                # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
└── esbuild.config.mjs         # Build configuration

Key Features

1. Voice Transcript Parsing

• Processes voice transcripts into atomic notes (one idea per note)
• Extracts actionable tasks and creates summaries
• Supports "auggie" voice commands for special behaviors
• Estimates token usage before processing

2. Linked Notes Distillation

• Analyzes a root note and all its linked notes
• Supports both standard Obsidian links and Dataview queries
• Deduplicates and merges overlapping ideas
• Creates comprehensive summaries with source attribution

3. Custom Context Instructions

• Users can add context: sections to notes for focused extraction
• Context instructions guide AI processing behavior

Development Guidelines

Build Commands

# Development build with hot reload
npm run dev

# Production build
npm run build

# Type checking
npm run typecheck

Code Standards

• TypeScript with strict mode enabled
• ESLint configuration for code quality
• No external runtime dependencies (only Obsidian API)

Testing

Currently no automated tests. Manual testing through Obsidian's developer console.

API Integration

OpenAI Service

• Model: GPT-4.1-2025-04-14
• Temperature: 0.7 for parsing, 0.3 for distilling
• Structured output using JSON schema
• Token estimation before API calls

File Operations

• Creates atomic notes in configurable folders
• Generates summaries with backlinks
• Handles special characters in filenames
• Maintains backlink mappings for navigation

Configuration

User Settings

• openaiApiKey: Required for AI processing
• summaryFolderPath: Default "OpenAugi/Summaries"
• notesFolderPath: Default "OpenAugi/Notes"
• useDataview: Enable/disable Dataview integration

Build Configuration

• Target: ES2018/ES6
• Platform: Browser (Electron)
• External: Obsidian modules
• Sourcemaps enabled for development

Output Structure

Summary Files

• Format: [original-name] - summary.md or [original-name] - distilled.md
• Contains: Summary, atomic note links, extracted tasks
• For distilled notes: Shows source note references

Atomic Notes

• Self-contained ideas with context
• Includes relevant backlinks
• Organized by timestamp or topic

Common Development Tasks

Adding New Features

1. Extend services in /src/services/
2. Update command registration in main.ts
3. Add settings if needed in settings.ts

Debugging

• Use Obsidian's developer console (Ctrl+Shift+I)
• Check console for error messages
• Enable verbose logging in development

Publishing

1. Update version in manifest.json and package.json
2. Build production bundle: npm run build
3. Create release with main.js, manifest.json, and styles.css

Important Considerations

• Always handle API errors gracefully
• Respect rate limits and token usage
• Sanitize filenames to prevent filesystem issues
• Maintain backwards compatibility with existing notes
• Test with various note structures and edge cases

Future Enhancements

• Support for additional AI models
• Batch processing optimization
• Enhanced Dataview query support
• Customizable output templates
• Integration with other Obsidian plugins