Copilot Personal

AI assistant for Obsidian. Multimodal chat with real streaming, RAG semantic search, autonomous agent (17 tools), 11 LLM providers, multi-provider fallback, PDF processing with unpdf, Free/Pro licensing with cloud validation + grace period, CircuitBreaker on all providers, dual-build (store/obfuscated), full i18n with 12 languages. 385 tests. TypeScript strict mode. And more: Smart Anti-Loop · Plan Detection · TOC Redirect · Keyword Tool Narrowing · Custom Agent Instructions · Complete Model Lists · /search-history · /list-chats · /load-chat · /batch-process · Popout Window · Free Trial (Copilot AI)

📖 Spanish documentation

⚠️ Commercial Disclosure: This plugin offers a Free tier (unlimited basic chat, bring your own API key, 3 tools) and a Pro tier ($4.99/mo via Lemon Squeezy) that unlocks Agent Mode, web search, semantic RAG, PDF image extraction, and multi-provider fallback. The Pro tier requires a paid license key validated against a Cloudflare Worker (copilot-personal-worker.copilot-personal.workers.dev). No account or payment is required for the Free tier. No telemetry or analytics are collected.

Key Features

Screenshots

Agent mode with $0 budget provider reading a PDF, summarizing it, and creating a note — all in two messages.

Chat in a separate popout window using the built-in Copilot AI provider. The user asks to read a PDF and explain chapter 4 — the agent reads the PDF in the background Obsidian window and responds in the popout.

Architecture

src/
├── main.ts                          # Plugin entry point
├── settings.ts                      # Settings interface & defaults
├── settingsTab.ts                   # Settings UI tab
├── chatView.ts                      # Chat ItemView (main orchestrator)
├── constants.ts                     # Centralized constants
├── LLMProviders/                    # 11 providers with native tool calling
│   ├── providerTypes.ts             # LLMProvider interface, capabilities
│   ├── providerManager.ts           # Factory: auto-detect & multi-provider routing
│   ├── deepseekProvider.ts          # DeepSeek (OpenAI-compatible + thinking mode)
│   ├── openaiProvider.ts            # OpenAI / OpenAI-compatible APIs
│   ├── anthropicProvider.ts         # Anthropic Messages API (native input_schema)
│   ├── geminiProvider.ts            # Gemini API (native functionDeclarations)
│   └── baseOpenAIProvider.ts        # Shared logic for OpenAI-compatible providers
├── agent/                           # Autonomous agent system
│   ├── ToolRegistry.ts              # Singleton: register, get, execute tools
│   ├── AgentModeRunner.ts           # Main tool-calling loop
│   ├── ToolRouter.ts                # LLM-based task classification → tool selection
│   ├── PlanTracker.ts               # Execution plan state tracking
│   ├── ContextCompactor.ts          # Map-Reduce context summarization
│   └── ContextLayers.ts             # L1-L5 context layer system
├── tools/                           # 17 agent tools
│   ├── FileParserManager.ts         # PDF, image, text file parsers
│   ├── readNoteTool.ts              # read_note (4 search strategies + path traversal protection)
│   ├── readPdfTool.ts               # read_pdf (TOC + pages + auto-find)
│   ├── createNoteTool.ts            # create_note
│   ├── updateNoteTool.ts            # update_note (post-write verification)
│   ├── renderPdfPagesTool.ts        # render_pdf_pages (pages to PNG, 144 DPI)
│   ├── extractPdfImagesTool.ts      # extract_pdf_images (embedded images + fallback)
│   ├── imageAnalysisTool.ts         # analyze_image (vision model)
│   ├── semanticSearchTool.ts        # search_vault_semantic
│   ├── webSearchTool.ts             # search_web (browser-use microservice)
│   └── additionalTools.ts           # list_notes, fulltext_search, vault_stats, etc.
├── search/                          # RAG semantic search
│   ├── vectorStoreManager.ts        # In-memory cosine similarity + JSON persistence
│   ├── indexOperations.ts           # Chunking, embedding, batch indexing
│   ├── indexEventHandler.ts         # Auto-reindex on create/modify/delete
│   ├── hybridRetriever.ts           # Hybrid search (vector + fulltext)
│   └── reranker.ts                  # Result re-ranking
├── services/
│   ├── LicenseManager.ts            # Cloud-first license validation + rate limiting
│   ├── BudgetManager.ts              # Copilot AI usage tracking + free trial limits
│   ├── webSearchClient.ts           # HTTP client for Python microservice
│   └── lmStudioService.ts           # LM Studio model detection (/v1/models)
├── memory/
│   └── MemoryManager.ts             # Persistent conversation summaries
├── components/
│   ├── ChatHistoryBrowser.ts        # Chat history navigator
│   └── ApplyView.ts                 # Diff view for <!--save:-->
└── utils/
    └── pathUtils.ts                 # Path normalization, fetch fallback, timeouts
├── i18n/                              # 12-language translation engine
│   ├── index.ts                       # t(), setLanguage(), translation registry
│   ├── types.ts                       # Lang type, LANGS map, getLanguages()
│   ├── en.ts                          # English master (~600 keys)
│   └── es.ts                          # Spanish translations

Installation

Quick Install

cd "YourVault/.obsidian/plugins"
git clone https://github.com/JosefBelzer/Copilot-Personal.git
cd copilot-personal
npm install
npm run build

Build Modes

npm run build          # Obfuscated main.js (external distribution: ZIP, Gumroad, BRAT)
npm run build:store    # Clean main.js (PR to Obsidian Community Plugins)
npm run dev            # Dev mode with sourcemaps and watch

⚠️ For Obsidian Community Plugin submission: use ONLY npm run build:store.
Obfuscated builds (npm run build) will be REJECTED by reviewers. Obfuscation is for external distribution only.

Manual Install

1. Download ZIP from Releases
2. Extract to YourVault/.obsidian/plugins/copilot-personal/
3. Enable in Settings → Community plugins → Copilot Personal

Web Search Server (optional)

cd web_search_server
pip install -r requirements.txt
set COPILOT_WEB_TOKEN=your-secure-token
uvicorn main:app --host 127.0.0.1 --port 8000

Free vs Pro Licensing

🆓 Free (default)

• Unlimited basic chat (bring your own API key)
• No message limits on your preferred provider
• 3 tools: read_note, read_pdf, find_files
• 💰 Copilot AI Free Trial — 5 queries/day. No API key needed. Select 💰 Copilot AI from the provider dropdown. Try Pro features before buying.
• Pro options appear disabled (🔒) in settings UI

⭐ Pro ($4.99/mo via Lemon Squeezy)

• Unlimited messages · Agent mode (17 tools)
• Web search · PDF with images · Semantic RAG
• Chat export (MD/JSON) · Slash commands · Priority support
• Multi-provider fallback · Per-provider API keys
• 💰 Copilot AI (included) — Built-in managed AI provider. 50 queries/day. No API key needed.

💰 Copilot AI Budget Provider

Free Trial (5 queries/day): Any user can select 💰 Copilot AI from the provider dropdown — no API key, no license, no configuration. Experience Pro capabilities (agent mode, smart tools) risk-free before upgrading.

Pro (50 queries/day): Included with Pro at no extra cost. Select 💰 Copilot AI (Pro) from the provider dropdown. 50 queries/day, tracked server-side per license. Monitor usage via the badge in the chat header.

⚠️ Agent Mode increases consumption — each step counts as one query. A 3-step task = 3 queries.

Activating Pro

1. Purchase a Pro subscription at belzersoftware.lemonsqueezy.com
2. Receive your License Key via email (Lemon Squeezy UUID format, e.g., 056b9494-...)
3. Settings → Copilot Personal → License Key → paste the key
4. You'll see ✅ Pro license activated successfully.
5. Chat badge changes to ⭐ Pro

License Security

Privacy & Security

• API keys: Stored locally in data.json. Each provider has its own field — switching providers won't leak keys. Masked (type="password") in settings UI. Never sent to plugin author's servers.
• Vault data: Sent only to your configured LLM provider. No telemetry or analytics.
• Vault enumeration: This plugin calls vault.getFiles() and vault.getMarkdownFiles() to enable semantic search (RAG), file lookup tools (find_files, read_note), and auto-save post-processing. File contents are only read when explicitly requested by the user or the agent.
• Web search: Requires a local Python microservice (web_search_server/). Authentication token is configurable in settings.
• License validation: Pro keys are validated against the Cloudflare Worker. Free tier requires no internet connection.
• Path traversal: Multi-layer protection against directory escape attacks in read_note.
• Timing-safe auth: Admin endpoint uses constant-time comparison for secret tokens.
• sessionStorage: Used only for temporary chat session crash recovery (auto-saved every 30s, cleared on new chat). All persistent data uses Obsidian's loadData()/saveData() API.
• No telemetry, no analytics, no tracking.

Development

npm install           # Install dependencies
npm run build         # Obfuscated build (external distribution)
npm run build:store   # Clean build (Obsidian store submission)
npm run typecheck     # TypeScript check only
npm run dev           # Watch mode
npx jest --verbose    # Run 385 tests across 27 suites

Testing

27 test suites (385 tests) covering: license management, circuit breaker, provider auto-detection, tool registry, agent detection, read/write tools, PDF tools, vector store CRUD, index operations, LM Studio service, settings, singleton reset, chat flow, path utilities, dom utilities, tool router, plan tracker, context compactor, context layers, auto-save manager, constants, i18n, budget manager, chat session. Run with npx jest --verbose. ⚠️ New features under development — see current work below.

Notes

• Legacy API key migration: If you previously stored your API key in the old single-key field, it is automatically migrated to the per-provider key on first load after upgrading to v1.4.4.

Current Development

Current development status for v1.6.2:

License

MIT License — see LICENSE file for details.