Combox User Guide

A detailed guide covering everything from installing Combox to using each of its features.

Installation

Requirements

macOS 13.0 or later
Combox trackball device

Installation steps

Place the Combox app (Combox.app) in the /Applications folder
Launch the app
The Combox icon appears in the menu bar

First-time Setup (Permissions)

To use Combox, the following system permissions are required.

Accessibility permission

Used to monitor and simulate input events.

A permission request dialog appears on first launch
Open "System Settings" → "Privacy & Security" → "Accessibility"
Enable Combox

Input Monitoring permission

Used to capture raw input from the trackball.

A permission request dialog appears on first launch
Open "System Settings" → "Privacy & Security" → "Input Monitoring"
Enable Combox

Note: After changing permissions, you may need to restart the app.

Menu Bar

Combox lives in the menu bar. Click the icon to open the following menu.

Menu item	Description
Enable / Disable app	Temporarily turn Combox on/off
Launch at Login	Launch automatically when you log in to macOS
Open Settings...	Open the settings window
Export Diagnostics...	Save a diagnostics ZIP for troubleshooting
Share Diagnostics...	Share the diagnostics information another way
Copy Support Info	Copy support information to the clipboard
Enable / Disable verbose logging	Toggle detailed logs for debugging
Quit Combox	Quit the app

Settings Window

Choose "Open Settings..." from the menu bar to open the sidebar-style settings window.

Item	Description
General	Basic app-wide settings
Pointer	Cursor movement settings
Scroll	Scroll behavior settings
Buttons	Physical button assignment settings
Combos	Simultaneous button press settings
App	Per-application profile settings
Backup	Export and import settings
Info	Version and debug information

General

Setting	Description	Default
Enable app	Turn Combox on/off	ON
Launch at Login	Launch automatically at login	OFF
Language	Choose from "Match System", "Japanese", or "English"	Match System
Enable verbose logging	Record detailed logs for debugging	OFF
Move cursor to dialog	Move the cursor to the default button when a dialog appears	ON

Pointer

Adjust the trackball's cursor behavior.

Setting	Description	Range	Default
Speed multiplier	Base pointer speed	0.05x – 5.0x	1.0x
Enable acceleration	Toggle speed-based acceleration on/off	—	ON
Acceleration strength	How much acceleration is applied	0.0 – 20.0	2.0
Invert X axis	Reverse horizontal movement	—	OFF
Invert Y axis	Reverse vertical movement	—	OFF
Drag threshold	Movement amount counted as a drag	1 – 20 px	5 px

Per-modifier speed settings

You can set the pointer speed individually while holding each of the Command / Option / Shift / Control keys. Handy when you want to slow down for precise work or move quickly across a large display.

Axis lock

While holding a specific modifier key, you can restrict pointer movement to only the horizontal or vertical direction.

Scroll

Setting	Description	Range	Default
Speed multiplier	Scroll speed	0.1x – 5.0x	1.0x
Inertial scrolling	Enable/disable scroll inertia	—	ON
Reverse direction	Reverse the scroll direction	—	OFF
Scroll mode	Choose from "Vertical", "Horizontal", or "Auto"	—	Vertical
Enable acceleration	Toggle scroll acceleration on/off	—	ON
Acceleration strength	How much acceleration is applied	0.5 – 50.0	2.0

Display zoom with Cmd + scroll

Holding the Command key while scrolling can trigger the macOS display zoom feature.

Buttons

Assign an action to each of the four physical buttons on the Combox trackball.

Button layout

[Top-left]  [Top-right]
[Bottom-left]  [Bottom-right]

Per-button settings

Setting	Description
Single-press action	What happens when you briefly press the button
Long-press action	What happens when you press and hold the button
Response timing	"Immediate response" or "On-release response"

About response timing

Immediate response — The action runs the moment you press the button. It cannot be combined with drag detection
On-release response — The action runs when you release the button. This makes it easier to distinguish from long-press and drag

Available actions

Action	Description
None	Do nothing
Left click	A standard left click
Right click	Show the context menu
Middle click	A wheel click
Mouse back	Corresponds to "Back" in browsers and similar apps
Mouse forward	Corresponds to "Forward" in browsers and similar apps
Mission Control	Launch macOS Mission Control
Launchpad	Open Launchpad
Keyboard shortcut	Register a shortcut such as ⌘C or ⌘V
Key press	Send a single key press
Launch app	Launch a specified application
Scroll	Perform a scroll action
Change scroll direction	Temporarily change the scroll direction

Registering a keyboard shortcut

Select "Keyboard shortcut" as the action
Shortcut recording mode starts
Press the key combination you want to register (e.g., ⌘+C)
The shortcut is registered

Launch app settings

Select "Launch app" as the action
The application picker appears
Select the application you want to launch

Combos

You can define "combo" actions that combine two buttons.

How combos work

Ordered combo — Triggered by pressing buttons in a specified order (e.g., Bottom-left → Top-right)
Combo recognition time — Adjust the window in which two button presses are recognized as a combo (200–500ms, default 300ms)

Creating a combo

Open the "Combos" tab in the settings window
Press the "+" button to add a new combo
Select the two buttons that make up the combo
Set the action to run when the combo triggers
Toggle the combo on or off

Combo recognition priority

When multiple actions conflict, they are handled with the following priority:

Drag (highest)
Combo
Long press
Single press

App Profiles

You can apply different button assignments and pointer/scroll settings for each application you use.

How profiles work

When the frontmost application changes, the corresponding profile is applied automatically
A profile can override the following settings individually:
- Pointer settings
- Scroll settings
- Button assignments
- Combo settings

Creating a profile

Open the "App" tab in the settings window
Press the "+" button to add a new profile
Select the target application
Configure the settings you want to override
Toggle the profile on or off

Examples

Browser: Assign "Back" and "Forward" to buttons
Figma / Photoshop: Assign the "Hand tool" shortcut to the middle click
Xcode: Assign the build shortcut (⌘B) to a combo

Backup & Restore

Exporting settings

Open the "Backup" tab in the settings window
Press the "Export" button
Choose a save location and the settings are saved as a JSON file

The export includes:

All app settings
Button assignments
Combo settings
Pointer/scroll settings
App profiles
Metadata (export date, app version, device information)

Importing settings

Open the "Backup" tab in the settings window
Press the "Import" button
Select the JSON file you exported
Validation runs on import
If there are no issues, the settings are applied

Note: Running an import overwrites your current settings. Back up your settings beforehand if needed.

Info (Debug & Version)

The "Info" tab in the settings window lets you check the app's status.

Information you can check

App version
Device connection status
Permission status (Accessibility / Input Monitoring)
Real-time debug log — Shows input event processing in real time

Using the debug log

When a button does not respond or an unexpected action runs, checking the debug log can help identify the cause.

Troubleshooting

Buttons do not respond

Make sure "Enable app" is selected from the menu bar icon
Make sure Combox is enabled under "Accessibility" and "Input Monitoring" in System Settings
Make sure the trackball device is connected correctly

Actions do not run correctly

Make sure the Accessibility permission is granted
Make sure the button assignments are set correctly in the settings window
Check the debug log on the Info tab to confirm input events are processed correctly

App profiles do not switch

Make sure the target application is in the foreground
Make sure the profile is enabled
Make sure the target application name is set correctly

Collecting diagnostics

If the issue persists, choose "Export Diagnostics..." from the menu bar to create a diagnostics ZIP and share it with support. The diagnostics include:

App information
A snapshot of the settings
Runtime status
Recent event logs
Log files