TECHNICAL.md

Technical notes

Requirements

• macOS 14 or later
• Swift 6.2 or later
• Ollama with a tool-capable model for the assistant

Run from source

swift run Refman

The assistant uses qwen3:14b by default. Override its model or host with REFMAN_OLLAMA_MODEL and REFMAN_OLLAMA_HOST.

Build the app

scripts/build_app.sh
open dist/Refman.app

The bundle includes the SwiftUI app and refman-agent. The build script signs the app ad hoc; set SKIP_CODESIGN=1 to skip signing.

Unsigned releases clear their quarantine attribute during installation and after in-app updates.

Test

swift test
python3 scripts/acp_smoke.py

The ACP smoke test requires Ollama.

Chrome extension

cd extension
npm install
npm test
npm run package

In chrome://extensions, enable Developer mode, choose Load unpacked, and select extension/refman-chrome-extension. Pair it from Refman → Settings → Chrome Extension.

Architecture

Sources/RefmanCore/    UI-independent database, storage, metadata, citation, and ACP logic
Sources/Refman/        SwiftUI application
Sources/RefmanAgent/   ACP-to-Ollama bridge
Tests/RefmanCoreTests/ Core tests

The library uses SQLite through GRDB with FTS5 full-text search. PDFs are stored by SHA-256 digest under ~/Library/Application Support/Refman/Storage.

Imports extract PDF text, detect DOI and arXiv identifiers, and resolve metadata through Crossref and the arXiv API. PDF annotations are written to the document and mirrored to SQLite.

The assistant communicates over the Agent Client Protocol. refman-agent bridges ACP to Ollama and exposes library search, document text, and annotation tools.

Acknowledgments

Citation formatting uses citeproc-js and resources from the Citation Style Language project. Bundled CSL styles and locales retain their author and contributor metadata and are distributed under CC BY-SA 3.0.

Project provenance

Refman was produced from natural-language prompts using Claude Code. Its source code was generated by Claude rather than written manually.

See todo.md for planned work.