Refman

A native macOS reference manager (Mendeley-style), built with Swift.

🤖 Vibecoded with Claude. This project is written end-to-end by Claude (Anthropic) via Claude Code — every line of code, from the database layer to the SwiftUI app to this README, produced by AI from natural-language prompts. No line was hand-written. Enjoy it for what it is.

• Library: SQLite (GRDB) with FTS5 full-text search; PDFs stored content-addressed by sha256 under ~/Library/Application Support/Refman/Storage.
• Import: drag-and-drop or ⌘I; extracts text via PDFKit, scans for DOI/arXiv IDs, resolves metadata against CrossRef and the arXiv API. .bib/.ris import too.
• Reader: PDFKit viewer with highlight/underline/note annotations, written into the PDF itself and mirrored to SQLite (searchable, listable, syncable).
• Export: BibTeX, RIS, CSL-JSON.
• Assistant: local-LLM chat over the Agent Client Protocol. The app spawns refman-agent (an ACP↔Ollama bridge) and exposes library tools (search_library, get_document_text, get_annotations, …) that the model calls to ground its answers in your actual papers.

Run

swift run Refman

Requirements: macOS 14+, Xcode toolchain. For the assistant: Ollama running locally with at least one tool-capable model pulled (e.g. ollama pull qwen3:14b). Override with REFMAN_OLLAMA_MODEL / REFMAN_OLLAMA_HOST.

Build a macOS app

scripts/build_app.sh
open dist/Refman.app

The bundle includes both the SwiftUI app and the bundled refman-agent used by the Assistant. The script ad-hoc signs the app for local use; set SKIP_CODESIGN=1 to skip signing.

Because Refman isn't signed with an Apple Developer ID, macOS Gatekeeper blocks it on first launch ("Apple could not verify… is free of malware"). Clear the quarantine flag once (sudo is needed because the app files aren't owned by your user), then open it normally:

sudo xattr -dr com.apple.quarantine /Applications/Refman.app

After the first install, the app updates itself: Refman → Check for Updates… pulls the latest GitHub release and relaunches, no quarantine step needed.

Test

swift test                      # 26 unit/integration tests
python3 scripts/acp_smoke.py    # end-to-end ACP agent test (needs Ollama)

Layout

Sources/RefmanCore/    # UI-free engine: database, storage, metadata, citation IO, ACP
Sources/Refman/        # SwiftUI app (library browser, PDF reader, assistant panel)
Sources/RefmanAgent/   # refman-agent: ACP agent bridging to Ollama
Tests/RefmanCoreTests/

See todo.md for status and roadmap (citeproc bibliographies and CloudKit sync across devices are the next phases).