Copilot Personal

Copilot Personal v1.4.1 — Obsidian AI Agent Plugin

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). 151 tests. TypeScript strict mode.

📖 Documentación en Español

⚠️ Commercial Disclosure: This plugin offers a Free tier (unlimited basic chat, 50 messages/day, 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

---

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
│   ├── 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

---

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
• 50 messages/day (persistent across restarts)
• 3 tools: read_note, read_pdf, find_files
• 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

Activating Pro

1. Purchase a Pro subscription
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 ✅ Licencia Pro activada correctamente.
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 151 tests across 16 suites

Testing

16 test suites 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.

---

License

MIT License — see LICENSE file for details.