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. It helps users process unstructured thoughts into a structured "second brain" by breaking down content into self-contained ideas.

The goal is to help humans process information faster.

Read the docs/CODEBASE_MAP.md to understand the project at a high level. Be sure to update this map as we make any siginficant changes.

Architecture Overview

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

Important: npm is not on the default PATH in this environment. Source nvm first:

export PATH="$HOME/.nvm/versions/node/$(ls $HOME/.nvm/versions/node/ | head -1)/bin:$PATH"

Then run commands as normal:

# Development build with hot reload
npm run dev

# Production build (includes typecheck)
npm run build

There is no standalone typecheck script — npm run build runs tsc -noEmit -skipLibCheck before bundling.

Code Standards

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

Testing

Automated test suite using Vitest with a mock Obsidian API. See docs/TESTING.md for full details.

# Run all tests
npm test

# Watch mode
npm run test:watch

Tests cover: filename utils, OpenAI prompt building, link extraction, BFS traversal, content aggregation, file output, journal filtering, backlink discovery. New features should include test coverage.

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

See docs/PUBLISHING.md for the complete release process, including community-store listing health and how to relist if de-listed.

Just run the script (it bumps all three version files, publishes, and verifies):

# write docs/release-notes/X.Y.Z.md first, then:
./scripts/release.sh X.Y.Z

Non-negotiables (the guard test tests/version-consistency.test.ts enforces these):

• Bump all THREE version files together: manifest.json, package.json, and versions.json (add "X.Y.Z": "<minAppVersion>"). Forgetting versions.json is the classic mistake.
• Tag == manifest.version, no v prefix.
• Publish the draft immediately after CI — never leave the repo advertising a version with no published release (that inconsistency can get the plugin auto-removed from the store).

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

Testing

My local testing vault is in: /Users/chris/zk-for-testing

Add any notes to /Users/chris/Documents/DEV-TESTING/Test to capture edge cases when relevant.