conjure/README.md

Conjure

A native macOS launcher for applications, calculations, unit and currency conversions, emoji, notes, and English → Japanese translation.

Build and install

Requires macOS 14 or later and a Swift 6 toolchain (Xcode 16 or later).

make run     # Build and launch .build/Conjure.app.
make build   # Build without launching.
make install # Install to /Applications/Conjure.app.
make test    # Run the test suite.

For a user-only installation:

make install INSTALL_DIR="$HOME/Applications"

Quit the installed copy before reinstalling. Installation does not request administrator privileges. Builds are ad-hoc signed by default and are not notarized for distribution. Ad-hoc signing ties Accessibility permission to a build's code hash: rebuilding and reinstalling can invalidate an existing grant even while Conjure remains enabled in System Settings.

To preserve permission across rebuilds, use the same code-signing certificate and app location every time:

security find-identity -v -p codesigning
make install CODE_SIGN_IDENTITY="<certificate SHA-1 from the list>"

Pass the same CODE_SIGN_IDENTITY to make build and make run too. If no identity is available, create a local certificate in Keychain Access → Certificate Assistant → Create a Certificate…, choosing Self Signed Root and Code Signing, or use an Apple-issued development certificate. Keep that certificate and its private key; recreating it changes the signing identity. After switching from ad-hoc signing, re-add Conjure to Accessibility once.

To work on the project, open Package.swift in Xcode. Run the bundled app for its application identity and metadata; make run restarts the development bundle so rebuilt code takes effect.

Getting started

Open Conjure, type an application name, and press Return to launch it or bring its running instance forward. Search supports partial names and initials, such as gc for Google Chrome. Favorites and frequently used entries rank higher among equally good matches.

Favorited launcher entries show a small star before their Application or Command label.

Launcher results and the emoji grid start below the top fade; scrolling moves content naturally through it.

Conjure searches the system and user Applications folders. Hover over a result to see its path; duplicate names show their locations. Drag the launcher background to reposition it; its position is remembered.

Conjure runs without a Dock icon. Dismissing the launcher leaves it running; reopen it from Finder or use your configured global shortcut.

The launcher, emoji picker, notes, and translation tool open immediately without window animations or content fades, including from global shortcuts. Shortcut destinations are prepared before the window appears. Settings is constructed only when needed, not before the launcher appears.

Controls

Action	Control
Select a result	Up/Down or Control-K/Control-J
Open a result or copy a calculated answer	Return or double-click
Open actions for the selected entry	Command-K
Open one of the first nine results	Hold Command until numbers appear, then press 1–9
Close the open action/provider picker, otherwise dismiss the launcher	Escape
Dismiss the launcher, including the current Command and pickers	Command-W
Open the translation provider picker	Command-P (in Translate)
Go back without dismissing	Back chevron
Open Settings	Command-comma
Quit	Command-Q

Right-click the launcher background for Settings and Quit. Actions include favorites, resetting usage ranking, revealing applications in Finder, quitting them, and uninstalling them.

Action and provider popups paint a popup-sized background using the launcher window’s gradient coordinates, keeping the glows continuous without showing the results underneath. Each opening rebuilds the complete native view and layer tree, rather than resizing a retained presentation between the footer and header. Callbacks and selection behavior stay in the controller. Layout finishes before the opening fade, including when switching popup types.

The launcher, emoji picker, and Translate share ActionPill for footer styling, alignment, spacing, and keyboard indicators: primary action with Return first, then Actions with separate Command and K keycaps. Controllers supply the buttons and retain their targets, enabled state, and popup behavior.

Global shortcuts and launch at login

In Settings, choose a Global shortcut destination: Applications, Conjure Emoji, Conjure Notes, or Conjure Translate. Choose Record Shortcut… and press a combination containing Command, Option, or Control. For example, select Conjure Emoji and record Command-Shift-Space to open the emoji picker directly. Clear disables only the selected destination's shortcut. No shortcuts are assigned by default; existing launcher bindings are preserved.

The Applications shortcut always targets the application launcher, not the last-used tool. Command shortcuts open their selected tool directly. Pressing a shortcut while its destination is already frontmost dismisses Conjure; switching destinations opens a fresh view. Active confirmations and uninstall operations are not interrupted. All global shortcuts pause while recording and resume afterward. Conjure rejects shortcuts already assigned to another destination or used by its own menus and navigation.

Cancelling recording, changing destination, or leaving the recorder restores saved shortcuts. If a replacement cannot be registered, the previous saved binding is retained; any failure to restore a shortcut is reported in Settings.

For Command-Space, select Applications and choose Use ⌘Space. If it conflicts with Spotlight, Input Sources, or another app, change that binding in System Settings first. Conjure never changes macOS shortcuts for you. Shortcuts work while Conjure is running; they do not start a quit app or require Accessibility permission.

Conjure lets macOS decide whether a global shortcut can be registered, rather than rejecting it solely because it appears in the system shortcut table. A registered shortcut can still compete with system behavior; if it does, change the conflicting system shortcut or choose another binding.

Install Conjure in /Applications, then enable Launch at login in Settings to start it in the background. If macOS requires approval, use Open Login Items Settings… to grant it.

Calculator and conversions

Type an expression into search and press Return to copy the answer. Arithmetic and unit conversions work offline.

(12 + 8) * 3
sqrt(144)
20% off 80
10ft in m
32 f to c
1 GiB to MiB
100 USD to DKK
0.5 BTC to ETH

Arithmetic supports powers (^), percentages, remainder (% or mod), scientific notation, pi/π, e, and the functions sqrt, abs, round, floor, ceil, sin, cos, tan, log, and ln. Trigonometric arguments are radians; log is base ten.

Convert length, mass, temperature, volume, duration, speed, area, and data with <amount> <unit> to <unit>; in and as also work. Data units distinguish bits (b) from bytes (B), and decimal (KB) from binary (KiB). Culinary volumes use US customary measures.

Currency and crypto conversions require internet access and use currency-api. These are daily rates, not live market prices; the snapshot date is shown with the answer. Treat them as estimates, not trading or payment quotes. Fetch failures show an error rather than silently using old rates; change the query to retry.

Rates are shared across queries and refreshed on the next currency query after the local day changes. While refreshing, a cached answer remains copyable and is labeled stale. Leaving the query or dismissing the launcher does not cancel that shared refresh.

ConjureKit.CurrencyCalculation owns this lifetime policy; the launcher renders its result. Its checks use an injected clock and scripted rate fetches.

Emoji picker

Search for Conjure Emoji, identified by its centered 🤔 icon, and open it. Browse the grid or search by name, keyword, :shortcode:, or emoji. Use the category menu to filter results or show Recently Used. Your last 30 selections are saved locally. Favorites appear first, followed by recent selections when browsing All Emoji.

Square 64-point emoji tiles use compact 1-point grid spacing and show the same subtle rounded border used elsewhere in Conjure only when selected or hovered; the selected tile retains its accent fill.

Use the arrow keys or Control-H/J/K/L to navigate left/down/up/right; the grid scrolls to keep the selected emoji visible. Return, clicking an emoji, or Copy and Paste copies it, dismisses Conjure, and tries to paste into the app that was focused when the launcher opened. Automatic pasting requires System Settings → Privacy & Security → Accessibility → Conjure; macOS prompts if permission is missing. After granting it, select an emoji again. If permission is denied, the previous app is unavailable, or focus cannot be restored promptly, the emoji stays copied for manual Command-V. The Back chevron returns to the launcher and restores your search.

If macOS keeps prompting despite an enabled Accessibility entry, quit Conjure, remove its stale entry with the minus button, add the exact app you launch (normally /Applications/Conjure.app), enable it, then reopen Conjure and retry. Avoid switching between installed and .build copies. For permission that survives rebuilds, configure certificate signing as described above. Copy Emoji followed by manual Command-V works without this permission.

Open Actions with Command-K for Copy and Paste (default), Copy Emoji (copy only, no Accessibility permission needed), Favorite, or Remove Favorite. Favorites are saved locally and grouped ahead of other emoji, with a small extra spacing break when browsing without a search. There are no star badges.

With Actions open, Escape or the Back chevron closes Actions first. Another Escape dismisses the launcher; another Back returns to Applications and restores your search. Command-W always dismisses the entire launcher, including the current Command and its Actions. Switching destinations also removes the previous Command's Actions completely. Copy and Copy and Paste dismiss the launcher without an intermediate Back step.

The picker works offline with 1,870 emoji from gemoji v4.1.0. Its MIT license is included in the application.

Notes

Search for Conjure Notes, identified by its centered 📔 icon, or assign it a global shortcut in Settings. New Note (Command-N) creates a note; the menu switches between notes, and reopening Notes restores the last selection. Each note’s first nonempty line becomes its menu title.

Edit Markdown directly: headings, bold, italic, lists, links, inline code, and fenced code blocks are highlighted while the source remains visible. Paste images or use Insert Image… to embed a local image. Command-Z undoes edits; Command-Shift-Z redoes them. Undo history is cleared when switching notes so edits cannot spill into another note.

Fenced code uses HighlighterSwift (Highlight.js) for language-aware token colors. Add a language after the opening backticks or tildes, for example py, python, swift, js, or json. Unlabeled fences use automatic detection; unknown languages remain plain monospace. Highlighting runs entirely offline.

Notes autosave locally as RTFD packages, including embedded images, under ~/Library/Application Support/Conjure/Notes. No account, network access, or cloud sync is involved. Save failures appear below the editor and prevent switching, closing, or quitting until saving succeeds, preserving the unsaved buffer. The Back chevron restores the launcher search; Escape or Command-W dismisses Conjure.

Translation

Search for Conjure Translate, identified by its centered 🌏 icon, and open it. Choose a provider in the pill-shaped header selector, enter text in the search bar, then press Return or click Translate. Typing alone never sends text. When the translation is available, the action changes to Copy: press Return or click it to copy the full translation and close Conjure. Command-C still copies selected output. Editing the input restores Translate.

The footer places Translate/Copy and its Return keycap before Actions, whose Command and K keys use separate keycaps, matching the launcher.

Press Command-P or click the provider selector to expand a searchable action-style popup from its top edge downwards, hiding the indicator until the popup closes. A checkmark marks the current provider. Use Up/Down and Return or click a provider to select it; Escape, Back, or clicking outside closes the popup. Changing providers clears the previous result without submitting a request.

The footer shows the current language pair (initially English → Japanese). Click it or open Actions with Command-K to change the source language, change the target language, or swap them. Language choices are saved locally and apply to both providers. Changing languages clears the previous result without submitting another request. The input hint and output accessibility label follow the selected pair. Escape closes an open action/provider picker first and dismisses the window only when no picker is open. Back closes the picker first, then returns to the launcher and restores your search. Command-W always dismisses the entire window.

Editing the input, changing languages or providers, saving or forgetting the key in Settings, or leaving Translate cancels the active request; cancelled results are not shown. After a request fails, submit again to retry.

• MyMemory: No account or key required. Limits are 500 UTF-8 bytes per request and 5,000 characters per day for anonymous use.
• OpenAI: Requires an API key, access to gpt-6-luna, and sufficient API billing. Manage the key in Settings > Conjure Translate: Save Key stores it in macOS Keychain; Forget Key removes it. Translate never saves a key implicitly. Requests disable API response storage, but OpenAI's retention policies still apply.

Translation sends your input to the selected third-party provider. Avoid sensitive content. There is no automatic fallback between providers. MyMemory never receives your OpenAI key.

Uninstalling applications

Select an application, open Actions → Uninstall application, and review the discovered files. Return toggles the highlighted file's inclusion; Command-Return opens confirmation. Back cancels review and returns to the launcher; Escape dismisses the entire launcher. Closing remains disabled while an uninstall is running, and confirmation sheets retain their own cancellation behavior.

Discovery looks for the application and associated files identified by its bundle IDs. Shared app-group data starts unchecked because other applications may use it. Review selections carefully: discovery is conservative, not a guarantee that every associated file is found. Protected applications and unsafe or inaccessible files cannot be removed. Running applications are asked to quit normally; Conjure does not force-quit them or request administrator privileges.

Selected files move to Trash, never permanent deletion. Finder's Put Back is unavailable for these moves; restore files manually using the original-path mappings retained under ~/Library/Application Support/Conjure/UninstallTransactions/Completed.

Interrupted uninstalls are recovered on startup. If recovery needs attention, Settings offers Retry uninstall recovery… and details of retained files. Keep the reported journal and quarantine paths until recovery is resolved. Recovery can require manual intervention if files are inaccessible, volumes are disconnected, or original paths have been recreated; unresolved recovery blocks new uninstalls.