conjure/README.md

# Conjure

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

## Build and install

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

```sh
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:

```sh
make install INSTALL_DIR="$HOME/Applications"
```

Quit the installed copy before reinstalling. Installation does not request administrator privileges. Builds are locally ad-hoc signed, not notarized for distribution.

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.

### 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 |
| Go back or dismiss the launcher | Escape |
| Dismiss the launcher | Command-W |
| 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.

### Global shortcuts and launch at login

In Settings, choose a **Global shortcut destination**: **Applications**, **Conjure Emoji**, 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.

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.

On macOS 27, [Siri AI uses Command-Shift-Space to select a window for screen capture](https://support.apple.com/en-is/guide/mac-help/iphmk4p88mkuky/mac). That system reservation can conflict even though it is not listed under Spotlight or Input Sources. Use another binding unless you have freed the Siri shortcut.

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.

```text
(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](https://github.com/fawazahmed0/exchange-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.

## 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.

Use the arrow keys or Control-H/J/K/L to navigate left/down/up/right. Return or clicking an emoji copies it and dismisses Conjure, restoring focus to the previous app. Paste with Command-V; no Accessibility permission is needed. Escape or the Back chevron returns to the launcher and restores your search.

Open **Actions** with Command-K and choose **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.

The picker works offline with 1,870 emoji from [gemoji v4.1.0](https://github.com/github/gemoji/tree/v4.1.0). Its [MIT license](Sources/ConjureKit/Resources/LICENSE-gemoji.txt) is included in the application.

## Translation

Search for **Conjure Translate** and open it. Enter English in the search bar, choose a provider, then press Return or click **Translate**. Typing alone never sends text. Copy selected Japanese output with Command-C; the copy hint appears beside the Translate action at the bottom. The Back chevron beside the input or Escape returns to the launcher and restores your search.

Editing the input, switching providers, forgetting the key, 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](https://mymemory.translated.net/doc/usagelimits.php) for anonymous use.
- **OpenAI:** Requires an API key, access to `gpt-6-luna`, and sufficient API billing. Choose **Save Key** to store it in macOS Keychain; **Forget Key** removes it. 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 or Escape cancels review.

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.