FluentKey

Polish your English instantly with a hotkey, anywhere on macOS.

Select awkward English (or Korean), press ⌃⌥C, and FluentKey rewrites it in fluent, natural English using your own OpenAI API key.

---

Features

• System-wide hotkey — ⌃⌥C works in any text field: Slack, iMessage, Notion, browser, terminal.
• Two correction modes — Polish awkward English into fluent English, or Translate Korean directly into fluent English. Mode is detected automatically from the selection.
• Three style presets — Casual / Formal / Concise, switchable via ⌘1 / ⌘2 / ⌘3 while the panel is open. Default is Casual (chat tone).
• Live streaming UX — first token shows in <500 ms; the corrected text streams in with a caret cue, no "loading…" wait.
• Diff highlighting — once the stream finishes, you see exactly what changed (insertions in mode tint, removals struck through).
• Replace, Copy, Cancel — ⏎ replaces the selection in place, ⌘C copies, Esc dismisses.
• Bring your own key — uses your OpenAI API key directly. Stored in macOS Keychain. No server, no telemetry, no account.

How it works

1. You highlight some text in any app.
2. You press ⌃⌥C.
3. FluentKey reads your selection (via the macOS Accessibility API), sends it to OpenAI with a tone-tuned prompt, and streams the corrected text into a small floating panel next to your cursor.
4. ⏎ writes the new text back into the source app — character-for-character, in the same field.

That's it. There's no menu bar UI to wrestle with, no separate window, no sign-in. The panel is the entire surface area.

Requirements

• macOS 13 (Ventura) or later
• An OpenAI API key (you pay OpenAI directly — typical use is fractions of a cent per correction)
• Xcode 15+ to build from source

Build from source

There are no pre-built releases yet — install by cloning and building.

# 1. Clone
git clone https://github.com/intersoom/FluentKey.git
cd FluentKey

# 2. Generate the Xcode project (project.yml → FluentKey.xcodeproj)
brew install xcodegen      # one-time
xcodegen generate

# 3. Build and launch
./run.sh

run.sh builds in Release, signs with a stable local identity (so macOS remembers your Accessibility grant across rebuilds), installs to ~/Applications/FluentKey.app, and relaunches it. After the first launch, grant Accessibility permission in System Settings → Privacy & Security so FluentKey can read your selection and write the replacement back.

Configuration

On first launch, FluentKey opens its Settings window:

• OpenAI API key — paste yours; stored in Keychain, never written to disk.
• Model — defaults to a fast chat model. You can swap to any chat-completion-compatible model on your account.
• Hotkey — defaults to ⌃⌥C.
• Default style — Casual / Formal / Concise.

After that, FluentKey lives quietly in the menu bar. You only see it when you hit the hotkey.

Privacy

• Your API key lives in macOS Keychain, encrypted at rest by the OS.
• Selections are sent only to OpenAI, only when you press the hotkey. Nothing is sent in the background.
• There is no FluentKey server. No analytics, no crash reporting, no telemetry.

Tech stack

• Swift 5.9 + SwiftUI — UI
• AppKit — floating panel, system menu integration, hotkey
• CoreGraphics — accessibility-API reads/writes for cross-app text exchange
• OpenAI Chat Completions API — streaming responses parsed via a small line-buffered SSE parser
• xcodegen — single source of truth in project.yml (the .xcodeproj is generated and gitignored)

Roadmap

Version	Status	Highlights
v1.0	shipped	Polish + Translate, hotkey, in-place replace
Phase 1	merged on main	Style presets (Casual/Formal/Concise), streaming UX, Edit menu shortcuts
v2.0 — Learning Loop	design sealed, awaiting product sign-off	Mistake Log, inline "Why this changed" tooltip, per-feature privacy toggles
v2.1 — Pattern Insight	design pending	Recurring-mistake detection across the log
v2.2 — Active Practice	design pending	Spaced practice on your own past mistakes

The visual and interaction language for every surface (current and planned) is documented in DESIGN.md — tokens, principles, and guardrails.

Development

The repo is small and self-contained:

FluentKey/
├── Sources/
│   ├── App/             # AppDelegate, coordinator, lifecycle
│   ├── Core/            # CorrectionService, OpenAI client, SSE parser
│   ├── Storage/         # Preferences, Keychain
│   ├── UI/              # CorrectionPanel, SettingsView
│   └── Resources/       # Assets, Info.plist
├── Tests/               # Unit tests (XCTest)
├── design/              # Icon SVGs and previews
├── scripts/             # Icon generator, signing setup
├── DESIGN.md            # Visual + interaction language (tokens, principles, guardrails)
├── project.yml          # xcodegen project definition
└── run.sh               # Build, sign, install, relaunch helper

Run the test suite:

xcodebuild -project FluentKey.xcodeproj -scheme FluentKey \
  -destination 'platform=macOS,arch=arm64' test

Contributing

Issues and pull requests are welcome. Before opening a PR for a non-trivial change, please open an issue first so we can align on direction.

The visual and interaction language is defined in DESIGN.md — please match its tokens, principles, and guardrails rather than re-deriving the design from prose.

License

MIT — do whatever you want, just keep the copyright notice.

Acknowledgments

• Icon concept inspired by the modern macOS/iOS-18 design language used by tools like Codex and cmux — single bold gradient symbol on a white squircle.
• Built for people who switch between Korean and English all day and want their English to land as naturally as their Korean does.