Show HN: Omabib, a Zotero alternative for Omarchy with agent support Omabib, a free AGPL-3.0-or-later Zotero alternative for Omarchy on Linux x86-64, launched with a built-in MCP server that lets Codex or Claude Code agents search references, retrieve PDFs, read notes and figure clips, and save project assessments. The app stores references and notes locally in SQLite with BibTeX import and export, and its bibliography, PDF reader, and notes work without an AI account; agent access runs on the user's existing provider account and billing. It installs via the command `omarchy plugin add https://github.com/atomashevic/omabib.git --enable`. A fast native Omarchy alternative to Zotero with first-class agent support. Free and open source. Search your library, read papers, capture ideas, and put your own agent to work with the references and notes you choose. - Fast, keyboard-first research. Search titles, authors, citation keys, abstracts, and notes from a native desktop window, with typo-tolerant search and a command palette. - Bring your own agent. Use Codex or Claude Code with your existing account. Chat beside the paper, in a terminal, or through supported desktop apps. Omabib itself requires no subscription; agent access uses your provider's account and billing. - First-class agent access. The built-in MCP server lets agents search references, retrieve PDFs, read notes and figure clips, and save project assessments when asked. Batch retrieval keeps multi-paper workflows efficient. - Read, clip, and ask. Open PDFs in reader tabs, select a passage to discuss, or clip a figure, table, or equation into a Markdown note with its page reference. - Notes that know the project. Keep shared bibliographic facts alongside separate project-specific notes, evidence, and assessments. - Your library, locally stored. References and notes live in SQLite, with BibTeX import and export. Optional sync carries your library across computers through storage you control. - Free software. Omabib is licensed under AGPL-3.0-or-later. The bibliography, PDF reader, and notes work without an AI account. Install install · First run first-run · AI setup optional-ai-setup · Sync sync · Update update · Troubleshooting troubleshooting For Omarchy on Linux x86-64 : omarchy plugin add https://github.com/atomashevic/omabib.git --enable Click the Omabib icon in your bar, then choose Install Omabib . It downloads the app and opens your library. The library starts empty. Open Add in the left rail, paste a DOI, arXiv ID, paper URL, or BibTeX entry, review the preview, and choose Import . To import an existing bibliography: omabib import /absolute/path/to/references.bib Search by title, author, citation key, or note text. Enter opens a paper's PDF or reference link; Tab opens its details, and Ctrl+K opens the command palette. Use Attach PDF to link a local file, or Open PDF to look for an open-access copy. Create a project from the command palette to group papers and keep project-specific notes. Check for existing bindings before adding these to ~/.config/hypr/bindings.lua on Omarchy installations using Lua configuration: o.bind "SUPER + B", "Omabib bibliography", "omabib open" o.bind "SUPER + ALT + B", "Omabib: add reference", "omabib add" Reload and check the configuration: hyprctl reload hyprctl configerrors Super+B shows and focuses Omabib, or hides it when already focused. Super+Alt+B opens the add box. Super+W closes the window through the normal desktop binding. You can always launch it with omabib open without adding shortcuts. Bring your existing Codex or Claude Code account for in-app and terminal chat, or use ChatGPT Desktop in Codex mode or Claude Desktop. The library, PDF reader, and notes work on their own. Open Settings using the cog at the bottom of the rail. Choose your installed agent under Terminal chat and Desktop chat . Terminal chat also needs xdg-terminal-exec available on PATH . In-app chat is available in a paper's Chat tab or the PDF reader's side pane. Choose Connect Codex in Settings to make the library available in your other Codex sessions. This registers the bundled MCP server and installs the Omabib skill. Reopen existing Codex sessions after connecting. From a terminal, the same setup is: omabib-settings register-codex Existing custom connections are preserved. Omabib's own Codex and Claude Code launchers already connect each chat to the current library. For Claude Desktop, use Add Omabib to Claude Desktop in Settings, then restart Claude Desktop. This merges the MCP entry into its configuration and saves a backup. ChatGPT Desktop opens a prepared draft in Codex mode; press Send to start the conversation. See Chat chat for context sharing, permissions, and saved conversations. omarchy plugin update io.github.atomashevic.omabib Open Omabib after updating. If the app needs an update too, the setup screen handles it. Your library and settings carry over. - Sort by newest addition to scan fresh Scholar alerts, then narrow the search to a project. - Open a paper's PDF in a reader tab, read it beside its notes and AI overview, and clip a figure, table or equation into a note with r . - Use the detail pane to inspect a reference's abstract, notes, files, and AlphaXiv overview. - Press the terminal button for a CLI chat Codex or Claude Code or the chat button for a desktop chat ChatGPT or Claude Desktop . Both receive a private reference snapshot with all project-labelled notes, image clips, and PDF paths, plus Omabib MCP access to the same library. - Ask an agent to compare project assessments, read a saved image clip, or retrieve the PDF. Library writes still require an explicit request. Open Super+B on the configured desktop, or run omabib open . An empty search field shows the newest additions first; Ctrl+S switches between date-added and citation-key order. Type a title, author, abstract term, citation key, or note fragment. Enter opens the PDF in a reader tab, or the reference link if there's no PDF. Ctrl+O opens the PDF specifically downloading an open-access copy first if none is attached ; Ctrl+U opens the reference's link/DOI specifically, skipping any attached PDF. Set OMABIB PDF SHORTCUT in the shell launch environment to change the PDF shortcut from Ctrl+O. Tab opens details. Ctrl+K opens actions. Esc hides the window; Q also hides it while the search field is empty, so searches can still contain q. Opening a link focuses the browser. The window has three panes. The rail on the left switches between all references A–Z , recently added, projects and Needs attention references missing an abstract or a PDF ; below them are Add, Sync sync now; its dot marks changes waiting, something to review or a sync issue , Sync settings and Actions. The list shows each result's title, authors and year with badges for PDF, AI overview, notes and a missing abstract; the filter button opens author, year, type and label filters. The detail pane has an icon toolbar Open PDF, Open link, New note, AI summary, Codex, ChatGPT, then ⋯ for Fill metadata, Edit BibTeX, Assign to project, Attach PDF, copy formats, Open PDF in another app and Delete and five sections: Overview abstract and metadata , AI summary arXiv papers only , Notes , Files and BibTeX . Ctrl+1–5 select a section and Ctrl+Tab cycles through them. Titles, abstracts, notes and the AI summary use a proportional reading font, Noto Sans by default; set OMABIB READING FONT in the shell launch environment to change it. The abstract and the AI summary are selectable: drag to select across paragraphs and press Ctrl+C, or use their Copy buttons the AI summary's copies the Markdown . The cog at the bottom of the rail or Ctrl+K action 24 opens Settings. Changes apply immediately and are saved in $XDG CONFIG HOME/omabib/settings.json ; omabib-settings prints or changes them from a terminal omabib-settings set ai cli claude . - PDF pages chooses Original colors or Omarchy theme colors for reader tabs see Theme colors theme-colors . Ctrl+R in a reader tab, the reader toolbar's half-moon button and action 27 switch it too. - Connect Codex registers the bundled MCP server for your active library and installs the current skill under $CODEX HOME/skills/omabib normally ~/.codex/skills/omabib . A matching connection is reused; a different or disabled connection is left unchanged. - Terminal chat chooses Codex CLI or Claude Code for the toolbar's terminal button and action 22 . - Desktop chat chooses ChatGPT Desktop or Claude Desktop for the toolbar's chat button and action 23 . Claude Desktop reads the library through Omabib's MCP server, which it loads from its own config: Add Omabib to Claude Desktop merges an omabib entry into ~/.config/Claude/claude desktop config.json , keeps everything else, and saves the original once as claude desktop config.json.omabib-backup . Restart Claude Desktop afterwards. The strip above the list starts with the library tab : the current project or All references , its reference count, and a chevron for the project picker. Papers open in paper tabs beside it, each showing that paper's detail at full width, and PDFs open in reader tabs see Reading PDFs reading-pdfs . The toolbar, palette and shortcuts act on the paper in the active tab. - Open: double-click a result, press Ctrl+T or Ctrl+Enter in search, or use the toolbar's new-tab button Ctrl+K action 25 . Middle-click a result to open it in the background. A paper that is already open switches to its tab. Results that are open in a tab carry a tab badge. - Switch: click a tab, Ctrl+PgUp/PgDn to cycle, Alt+0 for the library tab and Alt+1–9 for paper tabs. Ctrl+F , or typing while a paper tab is showing, returns to search. The search icon in a paper's toolbar finds it in the library tab. - Close: tabs stay open until you close them, including after hiding the window or restarting the shell. Close one with its ×, a middle-click, Ctrl+W or action 26 . Deleting a reference closes its tabs. - Limits: at most 12 paper and reader tabs together; opening another is refused until one is closed. Tabs shrink as they fill the strip, and when they no longer fit they overlap, with the active tab on top. Each paper tab remembers its section Overview, AI summary, Notes, Files, BibTeX . Tabs are kept per library socket in $XDG STATE HOME/omabib/tabs.json normally ~/.local/state/omabib/tabs.json , storing only reference IDs, citation keys, titles, the section, and for reader tabs the page and zoom. Ctrl+K opens the command palette. Type letters to filter it, or a number to run a numbered command as before; 1 · Add new item is the DOI/arXiv/URL/BibTeX add box see Adding references adding-references . For a first digit that could still start a two-digit action 1 or 2 , press Enter immediately or wait 700 ms for a possible second digit. Choose 7 · Import BibTeX file to browse folders or paste an absolute file path. Enter opens a folder or imports a file; Ctrl+L focuses the path. 6 · Paste BibTeX remains available. Use the palette to add a DOI, create projects, write notes, or copy bibliographies. DOI lookup is a preview; import is a separate action. No abstract is invented when metadata lacks one. Imports automatically consolidate repeated citation keys and identical entries within a file. Missing fields are combined; the first nonempty value wins when duplicates disagree, with conflicts reported. Entries with different DOIs remain separate. The importer also repairs unambiguous missing field commas, repeated fields, and a leading UTF-8 BOM. It retains the original imported text and leaves existing notes intact. Unclosed braces or undefined macros still produce an error instead of guessing or silently dropping records. To import a file: python omabib import references.bib omabib search 'network estimation' omabib status The normal library starts empty. Test fixtures and benchmarks use separate databases and are not imported into it. Paste a DOI, an arXiv ID, a paper's URL, several of those separated by spaces/commas, or a whole BibTeX entry — into the search field itself press Enter when there are no results and it's recognized , or 1 · Add new item / Super+Alt+B. Omabib fetches title/author/year, an abstract when one can be found, and an open-access PDF link, previews the citation key it would assign family word year , e.g. watts collective 1998 alongside each item, and only writes on Import. Adding a single identifier fetches and attaches its PDF automatically; an identifier already in the library is filled in rather than duplicated. After Import, the added or first, for several reference becomes the current search and detail view. For an arXiv paper, the AI summary tab checks alphaXiv for a published overview, caches it on first open, and lays the report out for reading: numbered section headings, lists, quotes and tables, with a strip that jumps between sections. Later opens use the local cache. alphaXiv reports open either with a Research Report: title or with a sentence of prose before 1. Authors ; both are accepted, and anything served as HTML is rejected. When no overview exists the tab says so and links to the paper on alphaXiv; the reference is unchanged. Delete… in the detail pane's ⋯ menu or action 21 in Ctrl+K previews the exact citation key and counts of notes, attachment links, project links, and cached summaries before confirmation. Deletion removes the reference and those library records atomically. PDF files stay on disk. With sync on, the deletion reaches your other computers. The MCP tools delete reference preview and delete reference expose the same reviewed operation; deletion requires the current revision and note/attachment counts from the preview, the exact citation key, and an idempotency key. Notes are Markdown. The note editor previews inline: every block renders except the one being edited, which shows its source; click a block, or move past its first or last line with ↑/↓, to edit it. Enter continues a list, and a second Enter or Enter on an empty list item starts a new block. Backspace at the start of a block joins it to the one above. The toolbar inserts headings, emphasis, quotes, lists, code and math; on an empty line code and math become fenced blocks. Inline $…$ or \ …\ and display $$…$$ or \ …\ math is rendered by the service render math and previewed under the block while you edit it; $5 and $10 stays text, and \$ is a literal dollar. Fenced code blocks show their language. Note cards and the AI summary use the same renderer. Notes are stored as plain Markdown, so search, MCP and sync use the source. Each note card in the Notes tab has edit and delete icons. Its confirmation shows the project and a note excerpt. Deleting one note removes its saved image clip and revisions but keeps the reference and its other notes. The MCP tools delete note preview and delete note provide the same operation with a current note revision, matching reference ID, and idempotency key. With Codex CLI selected, the terminal button in the detail toolbar or Ctrl+K action 22 opens a separate Codex CLI terminal for that entry. It passes a private context file containing metadata, BibTeX, all project-labelled notes, PDF/attachment paths, and exported image clips. Images are available for inspection on demand; MCP can retrieve current data and saved clips from the same library. The active project is the default scope for notes you ask Codex to save. Codex starts by acknowledging the entry, then waits for your question. With ChatGPT Desktop selected, the chat button or Ctrl+K action 23 opens a prefilled chat in ChatGPT Desktop Codex mode. It uses a stable Omabib workspace per library with gpt-5.6-sol and medium reasoning, a local Omabib skill, MCP pointed at that library, and a private snapshot for each entry. The draft remains unsent until you press Send. With Claude Code selected, the terminal button opens claude in a separate terminal with the same private context folder, the same opening prompt, and a per-launch MCP config mcp.json in that folder pointing at this library. Snapshots are kept under $XDG DATA HOME/omabib/claude . With Claude Desktop selected, the chat button opens a new Claude Desktop chat claude://claude.ai/new?q=… whose prompt asks Claude to load the entry, its notes, clips and PDF through Omabib's MCP tools, since Claude Desktop cannot read the local context file. The Codex terminal requires codex and xdg-terminal-exec . The chat uses gpt-5.6-sol with medium reasoning and a per-launch Omabib MCP override. Context snapshots are retained under $XDG DATA HOME/omabib/codex/chat- normally ~/.local/share/omabib/codex so a resumed chat can still read its files. The stable parent directory is the Codex working directory; Codex may ask you to trust it on first use. Each note body is bounded at 65,536 characters and explicitly marked if truncated. The library tab's chevron or the rail's folder icon, or Ctrl+P filters the whole result list to one project. Changing it keeps the current search text. If the focused reference is outside the new project, the detail pane closes and focus returns to search. Assign to project the + project chip or the ⋯ menu opens a separate project picker, including when All references is selected. omabib add 10.1145/3025453.3025717 by DOI omabib add arXiv:1706.03762 --project PROJECT ID by arXiv ID, linked to a project omabib add https://example.org/paper by URL, scraping its citation metadata omabib add --pdf /absolute/path/to/paper.pdf identified from the PDF's own DOI/arXiv ID or title omabib add --dry-run 10.1145/x 10.1145/y preview several at once, writes nothing Without a PDF or identifier, omabib add opens the add box in the Omabib window. add --no-pdf skips the automatic download. The JSON operation is add reference also an MCP tool ; preview entry previews without writing, and is what the popup calls before Import. identify pdf reads a PDF's first two pages for a DOI/arXiv ID, or falls back to a Crossref title search using its Title metadata. Data is stored at $XDG DATA HOME/omabib/library.db , defaulting to ~/.local/share/omabib/library.db . The socket is $XDG RUNTIME DIR/omabib/socket . OMABIB DB and OMABIB SOCKET override these paths for isolated libraries. The UI uses OMABIB SOCKET from its process environment and also accepts socket path in its summon payload for isolated testing. MCP setup and agent instructions are now included in Omabib. Update Omabib and choose Connect Codex in Settings, or run omabib-settings register-codex . A matching connection created by the old companion installer is reused and its skill is refreshed. You can remove the old companion checkout afterwards; your library is stored separately. The main repository's skills/omabib/SKILL.md https://github.com/atomashevic/omabib/blob/main/skills/omabib/SKILL.md is the authoritative agent guide. The companion repository is retired. Each reference has a stable UUID and a separately editable citation key. Global bibliographic facts are shared. Notes have an explicit project or global scope, optional labels/evidence, provenance, and a revision history. Multiple projects can assess the same reference differently. The CLI accepts structured JSON on stdin, avoiding shell-quoting problems: omabib call create project <<'JSON' {"name":"My project","roots": "/absolute/project/path" } JSON omabib call list projects <<'JSON' {"cwd":"/absolute/project/path"} JSON Use returned UUIDs in subsequent calls: omabib call add note <<'JSON' {"ref id":"REFERENCE UUID","project id":"PROJECT UUID","body":"Potential methodological comparison for this project.","labels": "method" ,"evidence":"PDF p. 7","provenance":"human","idempotency key":"A UNIQUE REQUEST ID"} JSON A global note explicitly uses "project id": null . An update supplies id and expected revision , as well as the current body, scope, provenance, labels and evidence. Stale revisions fail. Repeating the same request and idempotency key returns the previous result; reusing a key for different content fails. The stdio MCP server exposes search, retrieval, note, PDF, reference, and deletion tools. Use omabib schema for the current tool list and schemas; reconnect the MCP client after updating the executable. The installed omabib Codex skill covers selective retrieval, evidence-aware notes, reviewed deletions, adding references, and reading PDFs through get pdf . - Search defaults to eight results, capped at 25 per page. cursor continues the result set. - With a project, metadata is searched globally but note bodies are limited to global/current-project notes. Explicit include other projects broadens note search. - Without a project, search can discover notes from all projects, with attribution. - Fetching a reference does not include notes or attachments unless requested. Other-project note bodies remain opt-in. - project context defaults to 8,000 serialized characters. Follow its reference cursor; fetch a reference to obtain additional or unabridged notes. - The service never launches an LLM or extracts/indexes PDF text. It can validate, download, archive and restore PDF files. Paths are returned to agents; reading the paper remains their responsibility. omabib schema prints tool schemas and available CLI-only operations; omabib schema get reference search prints only those tools. See API.md https://github.com/atomashevic/omabib/blob/main/API.md for metadata, export and attachment operations. SQLite word/prefix and trigram indexes generate candidates. A separate title/author/key pass protects those matches. Rust ranks a bounded candidate set by field weight and a modest project boost. Exact keys/DOIs precede keyword, substring and typo stages. SymSpell handles one-edit misspellings for words of at least four characters, using library vocabulary. Numeric identifiers are excluded from typo dictionaries. This deliberately avoids exhaustive BM25 sorting of every match on every keystroke. Broad queries return a bounded ranked selection; the UI indicates when narrowing is useful. This is not a globally exhaustive relevance ordering. With an empty search field, the popup shows newest additions first; click the sort button or press Ctrl+S to switch to citation-key order. The date-added order uses a SQLite index and pages without sorting the whole library. Search terms keep relevance ranking. Typo vocabulary initializes in the background so keyword search can start immediately. Results include a short matching excerpt and attributed note matches, plus has pdf and has abstract . Search never sends full PDFs or the entire note collection to an agent. See VERIFICATION.md https://github.com/atomashevic/omabib/blob/main/VERIFICATION.md for measured results, test coverage and remaining limits. The synthetic scale fixture does not establish real-world search relevance. An identifier match DOI, arXiv ID, or a URL that resolves to one looks for an abstract automatically: the primary record Crossref or DataCite if it has one, otherwise OpenAlex, then Semantic Scholar, then Europe PMC — the first gateways not every publisher registers an abstract with. This runs for add reference , the popup's add box, and 17 · Fill metadata ; the abstract's source is reported alongside it. To backfill existing references that have an exact DOI or arXiv ID but no abstract yet: omabib enrich --abstracts --dry-run --limit 20 preview, writes nothing omabib enrich --abstracts fill the whole library, ~1 request/second It prints progress per reference to stderr and a summary filled, by source; not found; skipped for lacking an identifier; failed to stdout. It's resumable — already-filled references are skipped — so interrupting and rerunning is safe. omabib backup /absolute/path/library-backup.db omabib restore /absolute/path/library-backup.db --to /absolute/path/restored.db Backups use SQLite's consistent backup API. Restore validates the backup and only writes a new path. Stop the service before deliberately replacing the active library with a restored file. Do not copy a live database without its WAL; use backup instead. Future schema upgrades must take a backup before changing an existing schema. This release creates schema 1 and refuses newer versions. To remove Omabib while keeping your library: python3 ~/.config/omarchy/plugins/io.github.atomashevic.omabib/scripts/omabib-plugin remove-backend omarchy plugin remove io.github.atomashevic.omabib Removing only the plugin leaves the background service and CLI available. Agent registrations and your library stay in place; remove any agent registration separately if you no longer use it. For development, other architectures, or when no prebuilt release is available, install Rust/Cargo Typst requires Rust 1.92 or newer , Git, clang, and a C/C++ build toolchain. On Omarchy: sudo pacman -S --needed base-devel clang git rust git clone https://github.com/atomashevic/omabib.git cd omabib ./scripts/build.sh ./scripts/install.sh If you already installed the plugin with omarchy plugin add , use ./scripts/install.sh --backend-only after building to keep the Git-managed UI intact. If you manage Rust with rustup, omit rust from the package command and use a compatible toolchain. The build uses locked dependencies and compiles MuPDF from source; the first build can take several minutes. The installer uses target/release/omabib or $CARGO TARGET DIR/release/omabib , and also accepts an explicit binary path: ./scripts/install.sh /path/to/omabib . To update a source checkout, preserve any local changes, then run: git pull --ff-only ./scripts/build.sh ./scripts/install.sh - omabib command not found: open a new terminal or run ~/.local/bin/omabib open . Ensure ~/.local/bin is on your shell's PATH . - Prebuilt binary will not start: confirm the machine is Linux x86-64 uname -sm and inspect the error printed by bin/omabib --version . The binaries use glibc and system font libraries; they are not static or intended for musl-based distributions. - Build fails source installations : check rustc --version , cargo --version , clang --version , and make --version . A first build compiles MuPDF and Typst and can take several minutes. - Service is unavailable: inspect systemctl --user status omabib.service and journalctl --user -u omabib.service -n 50 --no-pager . After resolving the reported issue, run systemctl --user restart omabib.service and omabib status . - Installer reports that omarchy-shell is not responding: run it from an active Omarchy desktop session. Restore the shell, then rerun ./scripts/install.sh to complete installation. - The UI still shows an older version: close any open Omabib editor, unlock the desktop if needed, then run omarchy restart shell . - An unmanaged plugin already exists: the installer refuses to overwrite an Omabib plugin directory without its .omabib-managed marker. Inspect and back up that directory, then move it aside before rerunning the installer. How plugin setup works, and installing a release archive directly Omarchy manages the plugin checkout. On first use, Install Omabib downloads the matching version from this repository's GitHub Releases, checks its SHA-256 checksum, and installs the backend and launch helpers in your user account. It enables omabib.service , a systemd user service. No administrator access or build tools are needed. The download happens when you choose Install. If that version has not been released yet, the setup screen explains this and lets you retry later. Plugin updates keep the backend version matched to the UI. Release maintainers must publish matching assets before directing users to an updated plugin version. Existing installations keep the same library, settings, service name, and omabib command. Setup disables the old managed omabib plugin to avoid duplicate windows and leaves its files in place. The new plugin ID is io.github.atomashevic.omabib . You can also download omabib-VERSION-linux-x86 64.tar.gz from GitHub Releases https://github.com/atomashevic/omabib/releases , extract it, and run ./scripts/install.sh . This installs a standalone plugin copy; update it by installing a newer archive. A Git-managed plugin can use the same archive's ./scripts/install.sh --backend-only without changing its checkout. Installation paths and optional checksum verification | Component | Default location | |---|---| | CLI and launch helpers | ~/.local/bin/ | | Quickshell plugin | ~/.config/omarchy/plugins/io.github.atomashevic.omabib/ | | User service | ~/.config/systemd/user/omabib.service | | Omabib skill for Codex | ~/.codex/skills/omabib/ | | License texts and dependency notices | ~/.local/share/omabib/licenses/ | The prebuilt app uses Omarchy's standard runtime libraries, Bash, and Python 3. Rust and C/C++ build tools are needed only for source builds. To verify a downloaded archive, download SHA256SUMS from the same release into the same folder, then run: sha256sum --check --ignore-missing SHA256SUMS A matching archive prints OK . The release workflow https://github.com/atomashevic/omabib/blob/main/.github/workflows/release.yml builds on Ubuntu 24.04 x86-64, runs the Rust tests, packages and checks the installation, then publishes assets when a v tag is pushed. The tag must match the versions in both Cargo.toml and manifest.json ; update Cargo.lock alongside a package version change. Commit all code needed by the release before tagging. Each release includes: - omabib-VERSION-linux-x86 64.tar.gz : binary, QML plugin, helpers, user service, agent skill, and license texts. - omabib-VERSION-source.tar.gz : the tagged source with vendored Cargo dependencies, including native dependency sources. With the build toolchain installed, it can be built using ./scripts/build.sh --offline . - SHA256SUMS : SHA-256 checksums for both archives. A manual workflow run builds and retains test artifacts without publishing. To package an existing local build, run python3 scripts/package-release.py --version vVERSION ; add --source from a clean checkout to include vendored source. Packaging needs Cargo, Python 3.12 or newer, and network access for uncached dependencies. The release install test uses a temporary home and stubs desktop activation commands; a new release should also be checked in a real Omarchy session. cargo test --locked cargo clippy --all-targets -- -D warnings python scripts/test transport.py target/release/omabib omarchy plugin validate . python3 scripts/test plugin entry.py python3 scripts/test plugin lifecycle.py python3 scripts/test plugin backend.py target/dist/omabib-0.1.0-linux-x86 64.tar.gz python scripts/benchmark.py --directory /absolute/scratch/benchmark --binary target/release/omabib scripts/test metadata.py target/release/omabib makes live requests to Crossref/DataCite/OpenAlex/Semantic Scholar/Europe PMC/arXiv against a temporary, isolated library; run it only when checking those gateways specifically, since a busy run can hit Crossref's rate limit. The benchmark refuses to overwrite a database and uses synthetic metadata. scripts/test ui.py is an opt-in live keyboard test requiring an isolated socket; it interacts with the desktop and should run while no one else is typing. scripts/test tabs ui.py is the same kind of test for the detail tabs, the cached AI summary, the project menu and the command palette. scripts/test claude.py target/release/omabib checks the Claude Code and Claude Desktop handoffs and the settings helper against an isolated library and a temporary config directory. scripts/test chat agents.py target/release/omabib chats with the real Claude Code and Codex through an isolated service a read, then a write that must wait for approval ; it uses a few messages of each subscription. scripts/record chat fixtures.py target/release/omabib re-records the CLI event streams the chat adapters are tested against tests/fixtures/chat/ , scrubbed of personal details after a CLI update. The UI components render offscreen without a desktop: QT QPA PLATFORM=offscreen QT QUICK BACKEND=rhi QSG RHI BACKEND=opengl /usr/lib/qt6/bin/qmltestrunner -import tests/qml/imports -input tests/qml loads them against stub qs.Commons / qs.Ui modules and a stand-in for App.qml , and saves screenshots of every tab to /tmp/omabib-qml-shots create it first . The OpenGL backend is needed for the check of theme page colors; without it Qt renders in software, skips shaders, and that check is skipped with a warning. node scripts/test overview text.js overview.md tests the AI summary's Markdown renderer, optionally on a real overview file, and node scripts/test markdown.js tests the note features source line ranges, math, code blocks , and node scripts/test chat text.js the chat's tool labels, approval text and page links. V1 excludes automatically merging duplicate references, embeddings, and remote ChatGPT connectivity. identify pdf reads a PDF's first two pages to recognize an identifier or search by title, but that text is never stored or indexed for search — full-text PDF indexing and annotation remain out of scope. Sync keeps the library the same on all your computers, through storage you already have. Open it from the rail the cloud button , Settings → Sync… , or Ctrl+K action 20 . 1. Choose where: Google Drive, Dropbox, OneDrive, a folder on this computer kept in sync by Syncthing, Nextcloud or Dropbox's own app , or Other , any storage rclone reaches S3, R2, B2, WebDAV… . 2. Sign in: the cloud choices go through rclone https://rclone.org . If it isn't installed, Install rclone opens a terminal running omarchy-pkg-add rclone . Omabib opens the provider's sign-in page; after Allow , the dialog continues by itself. Dropbox's and OneDrive's pages name rclone, the tool Omabib uses to reach them. Google Drive requires your own OAuth desktop client for this source build; see the credential setup below. Its requested access is limited to files created by the app. 3. Start or join: the first computer uploads its library. On the next one, Omabib shows what it found "1,617 references, 13 notes, 17 PDFs, last synced from laptop 4 minutes ago" . An empty library joins with Use it . One with references offers Merge , which keeps everything from both, or Replace this computer's library . Either way the local database is backed up first to backups/before-sync- .db , and the three newest backups are kept. After that, sync runs in the service: - When: about 30 seconds after you stop editing, every 5 minutes, when the window opens, and when you press Sync. - Seeing changes: changes from other computers appear in the open window. - The Sync button: reads "Synced 2 min ago", "Changes waiting to sync", "Offline, will sync later", "Reconnect Google Drive" or "N sync changes to review". What syncs: - Records: references, notes with their clips , projects and project links, attachments and cached AI overviews. - PDFs: every PDF is uploaded. Cloud uploads group PDFs and clips into batches of eight with up to four concurrent transfers in one rclone process. Failed batches remain queued for retry. Other computers download one the first time it's opened Open PDF , or all at once with Download all in the Sync dialog. - Stays on each computer: chats, note revision history, and each computer's own file paths. - Storage layout: a visible Omabib/ folder with readable pdfs/