Skip to content

Latest commit

 

History

History
206 lines (150 loc) · 7.79 KB

README.md

File metadata and controls

206 lines (150 loc) · 7.79 KB

CodeController

Write software entirely using an Xbox controller and your voice. Maps every control you need for a voice-first, multi-terminal, agentic workflow to your gamepad.

Sit, stand, or walk around while developing software faster than ever.

Features

  • Face buttons — Common keys (Return, Escape, Backspace, Tab) with modifier layers

  • D-pad — Arrow keys, with modifier layers for tab and window switching

  • Two modifier layers — Hold LT or LB to access extended bindings on every button

  • Left stick — Moves mouse cursor (fallback for when buttons won't do)

  • Right stick — Smooth scrolling

  • Universal mouse buttons — Any button combo without a keyboard binding automatically emits a virtual mouse button (10–23), distinguished across modifier layers by held modifier keys (Option for +LT, Control for +LB). Mappable in utilities like SuperWhisper or BetterTouchTool

  • JSON config — All bindings stored in ~/.config/codecontroller.json, editable without recompiling

Requirements

  • macOS 10.15+
  • Xbox One wireless controller (known supported — other controllers may work via Apple's Game Controller framework)
  • Voice transcription — CodeController replaces your keyboard, so you need a voice-to-text app to type. SuperWhisper is recommended, but Whisper Transcription, Talon, or macOS Dictation also work

Setup

Check the Releases page for pre-built binaries.

Building from Source

Requires Swift toolchain (Xcode or Command Line Tools).

  1. Build: ./build.sh
  2. Copy to Applications: cp -R CodeController.app /Applications/
  3. Launch: open /Applications/CodeController.app
  4. Grant Accessibility permission when prompted (or manually in System Settings > Privacy & Security > Accessibility)

SuperWhisper (Voice Input)

SuperWhisper is a macOS voice-to-text app. Bind controller buttons to SuperWhisper for hands-free dictation:

  1. Install SuperWhisper
  2. Open SuperWhisper Settings
  3. Set Mouse Shortcut to Mouse Button 14 (RT)

BetterTouchTool (Extended Bindings)

BetterTouchTool can map any of the virtual mouse buttons (10–23) to system actions that CodeController can't do natively — switching Spaces, launching apps, window snapping, etc. Modifier layers emit the same button numbers but with held modifier keys (Option for +LT, Control for +LB), so BTT can distinguish them by matching on modifier state.

  1. Open BetterTouchTool Settings
  2. Enable Advanced > High Level Mouse Event Recognition
  3. Import the included preset: Preset > Import Preset, then select codecontroller_triggers.bttpreset from the app bundle (right-click CodeController.app > Show Package Contents > Contents/Resources) or the Releases page
  4. The preset maps LT+D-Left / LT+D-Right to switch Spaces (left/right)

Add your own triggers by assigning a mouse button to any action in BetterTouchTool's preferences.

Claude Code Keybindings

The default bindings map Y to Tab. Claude Code changed Tab from extended thinking toggle to autocomplete. To restore Tab as the thinking toggle, add this to ~/.claude/keybindings.json:

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "tab": "chat:thinkingToggle"
      }
    }
  ]
}

Default Bindings

Mouse buttons: Every button has a default mouse button number shown in the Mouse # column. All three layers (Base, +LT, +LB) use the same button numbers (10–23) — layers are distinguished by modifier keys held during the event: none for Base, Option for +LT, Control for +LB. The config file contains keyboard overrides — remove an override to expose the underlying mouse button. These virtual mouse buttons can be mapped in apps like SuperWhisper or BetterTouchTool.

Sticks

Input Action Mouse #
Left Stick Mouse cursor
Left Stick Click Left click 16
Right Stick Scroll
Right Stick Click Right click 17

Modifiers

Button Role
LT (Left Trigger) Hold to activate +LT layer
LB (Left Bumper) Hold to activate +LB layer

Base

Button Key Action Mouse #
A Return Submit 10
B Escape Cancel 11
X Backspace Delete 12
Y Tab Autocomplete / thinking 13
RT 14
RB 15
D-Up Up Navigate 18
D-Down Down Navigate 19
D-Left Left Navigate 20
D-Right Right Navigate 21
Back Ctrl+O Toggle transcript 22
Menu / Slash commands 23

+LT (mouse buttons held with Option)

Button Key Action Mouse #
LT+A Space Scroll page 10+Opt
LT+B 11+Opt
LT+X 12+Opt
LT+Y Shift+Tab Cycle permission mode 13+Opt
LT+RT 14+Opt
LT+RB 15+Opt
LT+LS 16+Opt
LT+RS 17+Opt
LT+D-Up <Accessibility> Cycle windows 18+Opt
LT+D-Down <Accessibility> Cycle windows 19+Opt
LT+D-Left Cmd+Shift+[ Prev tab 20+Opt
LT+D-Right Cmd+Shift+] Next tab 21+Opt
LT+Back Ctrl+E Toggle show all 22+Opt
LT+Menu 23+Opt

+LB (mouse buttons held with Control)

Button Key Action Mouse #
LB+A 10+Ctrl
LB+B Cmd+W Close tab 11+Ctrl
LB+X 12+Ctrl
LB+Y Cmd+T New tab 13+Ctrl
LB+RT 14+Ctrl
LB+RB 15+Ctrl
LB+LS 16+Ctrl
LB+RS 17+Ctrl
LB+D-Up 18+Ctrl
LB+D-Down 19+Ctrl
LB+D-Left 20+Ctrl
LB+D-Right 21+Ctrl
LB+Back Ctrl+B Background task 22+Ctrl
LB+Menu 23+Ctrl

Configuration

Bindings are stored in ~/.config/codecontroller.json. A default config is written on first launch. Edit the file and use Reload Config from the menu bar to apply changes.

The config only needs entries for keyboard overrides. Any button combo not in the config automatically emits its mouse button.

Binding Types

Type Description Fields
key Hold key (press on button down, release on up) key, modifiers
tap Fire once on press with explicit modifier key events — use for system shortcuts (e.g. Cmd+Shift+[) that don't register with key key, modifiers
leftClick Left mouse click —
rightClick Right mouse click —
cycleWindows Raise next window of frontmost app —

Example Bindings

{ "key": "return",  "type": "key" }
{ "key": "w",       "type": "key",   "modifiers": ["command"] }
{ "key": "[",       "type": "tap",   "modifiers": ["command", "shift"] }
{ "type": "leftClick" }
{ "type": "cycleWindows" }

Key Names

  • Letters: a through z
  • Numbers: 0 through 9
  • Editing: return, tab, space, backspace, escape, delete
  • Arrows: up, down, left, right
  • Function: f1 through f12
  • Punctuation: /, [, ], -, =, ;, ', ,, ., `
  • Navigation: home, end, pageup, pagedown

Modifier Names

  • command or cmd
  • shift
  • option or alt
  • control or ctrl

Binding Keys

Base buttons:

a, b, x, y, rt, rb, ls, rs, back, menu, dpad_up, dpad_down, dpad_left, dpad_right

Prefix with lt+ or lb+ for modifier layers (e.g., lt+a, lb+dpad_left).

Logs

Output is logged to ~/Library/Logs/CodeController.log.