KanataManager

A lightweight macOS Tahoe menu bar launcher/supervisor for Kanata.

This app helps run and manage Kanata in a user session without relying on Automator or Terminal windows.

Why This Exists

This project was built for personal daily use after upgrading to macOS Tahoe. Before Tahoe, Kanata was stable for me as a launchd background daemon on Sequoia.

After the Tahoe upgrade, that setup stopped working reliably because background daemon-style launches appeared unable to maintain the input-device permission model Kanata depends on.

I tested multiple startup patterns:

1. LaunchDaemon (old Sequoia setup)

• Previously worked for me.
• On Tahoe, no longer reliable for input-device permission access.

2. LaunchAgent + Terminal login script

• Could start Kanata at login.
• Ran in a visible Terminal session.
• Logout/restart/shutdown prompted to confirm stopping Terminal.
• Detaching/exiting Terminal eventually caused Kanata permission loss, so this was not stable long-term.

3. Automator app wrapper

• Solved permission stability issues.
• Removed visible Terminal session and shutdown prompts.
• But kept the persistent animated gear icon in the menu bar.
• Attempts to make it a hidden/background-only UI process caused permission loss again.

KanataManager is the practical compromise that worked for me: native menu bar app identity, stable startup behavior, and no Terminal/Automator UX drawbacks.

Project Scope

• This is a personal utility project that solved my Tahoe workflow problems.
• It is being shared publicly to help others facing similar Kanata-on-Tahoe issues.
• There is no broad feature roadmap.
• Future updates are likely only for compatibility adjustments with newer Tahoe/macOS changes.

Status

• Works as a native menu bar app (MenuBarExtra)
• Start / Stop / Restart Kanata
• Optional launch-at-login for the manager app
• Custom Kanata path/config/arguments
• Reads sudo password from Keychain item you configure

Screenshots

• Menubar Icon

  

• Menubar Popover

  

• Control Panel

  

Important

• This project does not include or bundle Kanata binaries.
• You must install Kanata separately (for example via Homebrew).
• You must have Karabiner virtual HID drivers already installed and working.
• App Sandbox is intentionally disabled in this project and is required for this launcher behavior.
• This project is independent from and is not part of or associated with the official Kanata project in anyway.

Requirements

• macOS Tahoe (26.x) or later
• Xcode 26.x (for building from source)
• Kanata installed locally
• Karabiner-DriverKit VirtualHID driver stack installed, allowed, and working

Quick Start

1. Clone this repo.
2. Confirm Karabiner virtual HID drivers are installed and functioning.
3. Open KanataManager.xcodeproj.
4. Build and run the app.
5. In the control panel, set:
   • Kanata binary path (example: /opt/homebrew/bin/kanata)
   • Kanata config path (example: ~/.config/kanata/kanata.kbd)
   • Keychain service/account used for sudo password lookup
6. Grant macOS permissions as prompted (Input Monitoring / Accessibility as needed).

Security Notes

• The app reads a password from your macOS Keychain and pipes it to sudo for start/stop operations.
• Review the source and adapt to your own security preferences.
• Prefer a narrowly scoped local setup and trusted machine usage.

Privacy

• This app is fully local and does not send telemetry or communicate with remote services.
• It only executes local system commands needed to manage Kanata (sudo, security, pgrep, pkill).

License

• This repository: MIT (see LICENSE)
• Third-party notice for Kanata / LGPL: see THIRD_PARTY_NOTICES.md