Astrolabe

Documentation

Astrolabe documentation

Setup and usage for the current macOS source build.

Release status

No public installer is available. The current version is 0.0.0.

Current build

Astrolabe augments knowledge work across Zotero, Obsidian, and Eagle through a local SQLite index. You can browse and filter documents, search indexed text, inspect document details, and open items in their source applications. Matching Zotero and Eagle files may be combined by SHA-256.

Where data lives

Astrolabe stores its generated database and its own folder definitions under ~/Astrolabe/.astrolabe/ by default. Set ASTROLABE_WORKSPACE before launch to use another workspace root.

Run Astrolabe from source

Requirements: macOS, Git, Node.js 24, and Corepack.

  1. Clone the repository

    git clone --branch rebuild --single-branch https://github.com/AhmedKhan-GH/astrolabe.git
cd astrolabe

  2. Install dependencies

    corepack enable
pnpm install

  3. Start the desktop app

    pnpm dev

    On first launch, Astrolabe creates the local workspace and starts a sync. Use the Sync button after starting or changing a source app.

Useful source checks 
pnpm typecheck
pnpm test
pnpm build

These commands type-check both processes, run the unit/component and integration suites, and build the Electron main, preload, and renderer bundles. They do not create a public installer.

Connectors

A sync probes each connector separately. If one source cannot be reached, Astrolabe marks that connector unavailable and keeps its previously indexed libraries dormant; the other connectors continue to work.

Zotero

Local API · personal and group libraries

Start Zotero before syncing. Astrolabe connects to Zotero's local API at localhost:23119, discovers My Library and the group libraries in the local client, and indexes bibliographic items, top-level attachments, tags, collections, and PDF annotations.

  • Stored attachment paths currently assume Zotero's default ~/Zotero data directory.
  • Linked attachments retain their absolute path when Zotero supplies one.
  • Open actions use Zotero deep links, including a PDF attachment link when available.

Obsidian

Local Markdown · multiple vaults

Astrolabe discovers vaults registered with the Obsidian desktop app by default. It recursively indexes readable .md files while skipping hidden directories and dotfiles. Titles, frontmatter and inline tags, note bodies, wiki-links, and contiguous Markdown blockquotes are parsed into the current index.

To add explicit vaults or use only a curated set, keep the generated fields in ~/Astrolabe/.astrolabe/manifest.json and add a connector block: 

"connectors": {
  "obsidian": {
    "vaultPaths": ["/absolute/path/to/Vault"],
    "discoverVaults": true
  }
}

Set discoverVaults to false to scan only the listed paths. Run Sync after changing the manifest. A missing vault is marked dormant rather than erased from the index.

Eagle

Local API · one open library at a time

Start Eagle with a library open before syncing. Astrolabe reads Eagle's local API at localhost:41595 and indexes non-trashed items, file types, tags, and the source folder tree for the open library.

  • The Libraries rail lists indexed libraries and libraries known from Eagle's history.
  • A switch action opens another library in Eagle and then syncs it.
  • Sync all Eagle libraries visits the known libraries and attempts to restore the one that was originally open.
  • Import from Eagle copies a synced source folder tree into new Astrolabe folders once; the two trees are not kept in sync afterward.

Eagle file hashing and reveal actions require filesystem access to the library directory. macOS may require a privacy permission for libraries in protected locations such as iCloud Drive.

Search and navigation

With no query, the document list is sorted newest first. Search uses SQLite FTS5. Folder, tag, and library filters apply to both browsing and search.

  • All shows non-ghost documents by default.
  • Uncategorized shows documents in no Astrolabe folder.
  • Result rows show kind, source copies, tags, and search snippets.
  • Click for details; double-click to open the first available source copy.
Keyboard shortcuts in the current interface
ShortcutAction
⌘/Ctrl KJump to a folder, document, or library.
⌘/Ctrl FFocus and select the main search field.
⌘/Ctrl [ / ]Move backward or forward through selection history.
⌘/Ctrl + clickToggle rows in a multi-selection.
Shift + clickSelect a range from the last anchor.
FFile the current selection to a folder.
Enter or OOpen the anchored result in its source app.
EscClear the selection.

The command palette matches folder paths and library names by substring. Document results begin after two characters and are returned by the same full-text index.

Astrolabe folders

Folders are local organization metadata, stored as JSON files under .astrolabe/folders/. Filing a document changes only its Astrolabe membership; it never moves, renames, or deletes the source item.

  1. Create a top-level folder with + New Folder.
  2. Right-click a folder to create a child, rename it, move it, or delete it.
  3. Select one or more document rows, then choose File to folder….
  4. While browsing a folder, use Remove from this folder to unfile the selection.
  5. On a selected parent folder, toggle ⊂ to include or exclude its descendants.

A document can belong to more than one folder. Deleting a folder leaves its documents untouched and reparents its child folders to the deleted folder's parent.

Ghosts

A ghost is an indexed document with no remaining source copy. Ghosts are hidden by default.

  • Show ghosts reveals hidden ghost records.
  • A ghost retains its title, kind, search entry, and folder membership but cannot be opened.
  • An unavailable library is marked dormant and does not become a ghost solely because it is unreachable.

Current limitations

  • Search is keyword-based. It does not extract PDF text or run OCR.
  • There is no in-app reader, editor, annotation write-back, or Smart Folder support.
  • The interface shows up to 200 browse results or 50 search results and has no pagination.
  • Sync runs at launch and when the user chooses Sync; there is no remote sync service.
  • No public installer has been released.