claudeers.
// Education & Learning

padpilot

Drive Claude Code, Codex and the Claude desktop app with a PS5 DualSense controller

// Education & Learning[ cli ][ api ][ desktop ][ web ][ claude ]#claude#education◷ MIT$open-sourceupdated about 7 hours ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up padpilot (git-clone project) into my current project.
Found on https://claudeers.com/padpilot
Repo: https://github.com/XixianWasTaken/padpilot
Homepage/docs: —
Detected install method: git-clone → git clone https://github.com/XixianWasTaken/padpilot
Category: education. Platforms: cli, api, desktop, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or clone
git clone https://github.com/XixianWasTaken/padpilot

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageHTML

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

padpilot: drive Claude Code and Codex with a PS5 controller

English · 中文

Lean back and drive your coding agent from the couch. padpilot turns a PS5 DualSense controller into a wireless remote for Claude Code, OpenAI Codex CLI, and the Claude desktop app:

  • See and feel what the agent is doing. The lightbar breathes blue while thinking, shifts colour by tool type, blinks orange with strong double pulses and a crisp R2 trigger click-point when waiting for approval, and turns solid green when done. Over USB, the controller's built-in speaker also plays status sound cues.
  • One button layout across every app. ✕ / R2 approves and submits, ○ / L2 cancels and interrupts, □ clears input, △ sends continue, R3 retries your last prompt, and holding △ opens an 8-direction prompt wheel. Your custom shortcuts in ~/.claude/keybindings.json are respected automatically.
  • Interactive built-in Pad School. Run padpilot tutorial (or /padpilot:tutorial in Claude Code) to learn the controls step by step with your real controller. While the tutorial page is open, practice mode is active so no presses ever reach your agent.

The tutorial page: Claude has finished a turn and asks whether to continue; on the controller picture, △ is highlighted

 Claude Code / Codex ──Hooks──▶ padpilot daemon ──HID──▶ DualSense (light / rumble / triggers / speaker)
        ▲                            │   ▲
        └──── keystrokes ◀───────────┘   └──── buttons / sticks / touchpad
     (PTY wrapper, or the Claude desktop app on macOS)

Install

Requires a DualSense controller (USB or Bluetooth), Python ≥ 3.8, and macOS (terminal features also work on Linux; Claude desktop app control is macOS-only).

git clone https://github.com/XixianWasTaken/padpilot.git
cd padpilot

# 1. Set up the runtime environment (installs hidapi into ~/.padpilot/venv) and add to PATH
./bin/padpilot setup
ln -sf "$PWD/bin/padpilot" ~/.local/bin/padpilot

# 2. Install the Claude Code plugin (hooks + slash commands)
claude plugin marketplace add "$PWD"
claude plugin install padpilot@padpilot

# 3. (Optional) Install Codex hooks (backs up ~/.codex/hooks.json first; run /hooks once in Codex to trust)
padpilot install-codex

# 4. Verify & explore
padpilot doctor             # check hidapi, controller, and daemon
padpilot demo               # test rainbow lightbar + rumble
padpilot tutorial           # open the interactive Pad School tutorial
padpilot manual             # open the bilingual reference manual

Three Ways to Use It

Add aliases to your shell profile for everyday terminal use:

alias cc='padpilot run claude'
alias cx='padpilot run codex'
ModeHow to startLights / Rumble / AudioApprovalsEveryday Button Control
1. Terminal Wrapper (Recommended)padpilot run claude / codex✓✕ approve / ○ denyFull keystroke injection (auto-detects DECCKM & Kitty keyboard protocol)
2. Claude Desktop App (macOS)Open the Claude desktop app✓Hook approval (45s timeout)Direct control of the input box, reply cards, question boxes & dictation while frontmost
3. Hook-Only Mode (IDEs / Raw CLI)Run claude / codex directly✓Hook approval (45s timeout)Approvals only; regular button presses are not sent

First-Time Setup for Claude Desktop App (macOS)

To send keystrokes and focus the input box in the Claude desktop app, grant Accessibility permission once:

padpilot desktop                    # opens the macOS Accessibility prompt (System Settings → Privacy & Security → Accessibility)
padpilot stop && padpilot desktop   # restart daemon and verify it reports "ok"
  • Permission is granted to the daemon's Python inside ~/.padpilot/venv. Keystrokes are posted directly to the Claude desktop app's process and only while it is the frontmost window.
  • When a padpilot run terminal session is also open, buttons go to the terminal by default—except when the Claude desktop app is frontmost with a mid-turn question box open (and the terminal session is not waiting for input), in which case R1 + face buttons and ✕ answer that question box.

What the Controller Tells You

1. Lightbar & Rumble

StateLightbarRumbleTriggered By
IdleSoft white, slow breathingTwo light taps on session startSessionStart
ThinkingBlue breathing–UserPromptSubmit / PostToolUse
Running a ToolFast breathing coloured by tool (flashes on each call)Per-tool tactile feedback (see below)PreToolUse
Needs ApprovalBlinking orangeTwo strong pulses (repeats after 20s, up to 3 times)PermissionRequest / permission prompt
Waiting for InputYellow breathingGentle nudgeQuestion box (Elicitation) or idle prompt
DoneSolid green until you press any button (kept up to 12h; turns over 60s play a 2s rainbow first)Success pattern (longer fanfare for 60s+ turns; gentle reminder after 10 min)Stop
ErrorBlinking redLong buzzStopFailure (API error)
Tool FailureSingle red flashShort buzzPostToolUseFailure
CompactingPurple breathing–PreCompact
Microphone in UseFast white breathing + mic LED onTap on start, tap on stopAny app actively recording audio (e.g. dictation)
Action UnavailableSingle red flashTwo short buzzes ("no")Unsupported action in target app, nothing to retry, etc.
Low Battery (≤15%)Red flash (1.2s)Two short buzzes (at most once every 5 min)Controller discharging at ≤15%

Tool Colours & Rumble (tool_kinds, matched across Claude Code and Codex tools):

Tool CategoryLightbar ColourRumble
Bash / shell commandsOrangeStrong tick
Edit / Write / apply_patchMagentaTwo low-frequency thuds
Read / Grep / GlobCyanLight tick
WebFetch / WebSearchBlueLight tick
Task / Agent (subagents)PurpleNudge
MCP tools (mcp__*)Mint greenLight tick

2. Adaptive Triggers, Player LEDs & Speaker

  • Adaptive Triggers:
    • Waiting for approval: R2 engages a tactile click-point—pull through the click to approve; L2 adds light resistance.
    • While the agent is working: L2 adds light resistance as a physical reminder that pulling it through interrupts (Esc).
  • Player LEDs (5 white LEDs below the touchpad):
    • During a turn: Acts as a progress bar, lighting an additional LED at 1 / 3 / 6 / 11 / 21 tool calls (or showing which session is focused when multiple padpilot run sessions are open).
    • Next-step cards: Lights 1 or 2 centred LEDs when stopped to show how many reply buttons on Claude's next-step card can be picked with R1 combos.
    • Context window warning: At the end of each turn, if token usage exceeds 80% of the model's context window, the solid green light slowly pulses between green and amber as a reminder to /compact or start a fresh session. Tapping PS shows context usage on the player LEDs (20% per LED) while the lightbar displays battery level (red to green).
  • Controller Speaker Cues (USB only, macOS):
    • Plays macOS system sounds through the DualSense's built-in speaker on state transitions: Glass on done, Ping on approval, and Basso on error.
    • Toggle anytime with PS + △ (persisted to config; plays Pop when enabled). Silent over Bluetooth, and never falls back to Mac speakers.

Buttons & Pro Moves

Every button maps to a semantic action (submit, cancel, clear_input, etc.) translated on the fly for the target app, automatically respecting your ~/.claude/keybindings.json and Claude desktop dictation shortcut. Run padpilot keys to inspect the exact keystrokes for your setup.

1. Button Reference

ButtonActionDesktop AppClaude CLICodex CLI
✕ / R2 pulled throughSubmit / Confirm / ApproveEnterEnterEnter
○ / L2 pulled throughCancel / Interrupt / DenyEscEscEsc
□Clear the input box⌘A + DeleteCtrl+U + Backspace–
△ tapType continue and send✓✓✓
Hold △ + right stickPrompt wheel (8 preset prompts, filled into input on release)✓✓✓
R1 + ✕ / ○ / □ / △Pick option 1–4 on next-step cards or question boxes✓––
R1 tapType / (open slash-command menu)✓✓✓
R3 (click right stick)Retry your last messageFills in (press ✕ to send)Resends immediatelyResends immediately
L1 tapCycle permission mode (e.g. Plan mode)–Shift+TabShift+Tab
L1 + ✕Queue message (without interrupting the active turn)⌘↩Ctrl+X Enter–
L1 + ○Stop all subagents–Ctrl+X Ctrl+K–
L1 + □Undo typing⌘ZCtrl+_–
L1 + △Open external editor–Ctrl+G–
L1 + ↑ / ↓Open model picker / thinking effort⌘⇧I / ⌘⇧EMeta+P / Meta+T–
D-pad / Left stickArrow keys (repeats while held)✓✓✓
Right stick ↑ / ↓ or touchpad swipePageUp / PageDown✓✓✓
Right stick ← / →Previous / next session⌘⇧[ / ⌘⇧]Switch padpilot run sessionsSame
OptionsShow changes / transcript⌘⇧DCtrl+OCtrl+T
Create tap / holdTap: cycle focused session · Hold: new session⌘N/clear/new
Touchpad click / swipe leftClick: rewind last message · Swipe left: search historyEsc Esc / –Esc Esc / Ctrl+REsc Esc / Ctrl+R
L3 (click left stick)Open command palette⌘K––
Mic buttonVoice dictation (tap to toggle, or hold >0.5s for push-to-talk)⌘D (reads app config)––
PS tap / holdTap: show battery & context · Hold: force-interruptEscCtrl+CCtrl+C
PS + ↑↓ / ←→Adjust lightbar brightness / rumble strength✓✓✓
PS + □ / △ / MicToggle idle light / speaker sounds / lock controller✓✓✓

Modifier Rule: PS, R1, and L1 act like Shift—hold one and press another button. Their own tap/hold actions fire only on release and are suppressed once a combo is used. Holding a button gives a subtle haptic tick as soon as the hold threshold is reached.

2. Pro Moves & Smart Safeguards

  • Prompt Wheel (Hold △ + Stick): Push the stick in any of 8 directions (continue, run the tests and fix failures, explain what you just did, stop and ask me first, commit, write tests for this, summarise the changes, keep fixing this bug). Each sector has its own lightbar hue and haptic tick. Releasing △ clears the input box and fills in the prompt without sending, so you can edit it or press ✕ to send.
  • Next-Step Cards & Question Boxes (R1 + Face Buttons):
    • Next-Step Cards: When the Claude desktop app presents a wrap-up card with reply buttons, R1 + ✕/○/□/△ clicks button 1–4.
    • Mid-Turn Question Boxes (Elicitation): While a question box is open, the lightbar breathes yellow. Use R1 + ✕/○/□/△ to pick option 1–4: single-choice questions submit immediately (or press ✕ alone to submit the default selection); multiple-choice questions toggle options with each R1 combo and submit when you press ✕.
  • Retry Last Prompt (R3): Resends your most recent message (in the desktop app, it fills the message into the input box without auto-sending so you can verify the active session first). Pressing R3 while the agent is still busy gives a two-buzz refusal; double-pressing R3 within 2 seconds forces a retry if you stopped the agent manually.
  • Smart Hook Approvals (Without padpilot run): In the desktop app or unwrapped CLI sessions, the PermissionRequest hook waits up to 45 seconds for ✕/R2 (approve), ○/L2 (deny), or △ (leave to screen), including ExitPlanMode plan approvals.
    • Non-blocking: Both the on-screen dialog and the controller wait simultaneously; whichever you answer first wins.
    • Presence-aware: Only waits if you used the controller within the last 5 minutes (or touched the controller more recently than the keyboard/mouse). Unattended background runs (claude -p) never trigger the controller.
    • 0.6s accidental-press guard: Presses within the first 0.6 seconds after a permission request appears are rejected with two short buzzes so an in-flight ✕ meant for typing never accidentally approves a command.

Configuration

Add only the keys you want to override in ~/.padpilot/config.json (deep-merged over DEFAULTS in padpilot/config.py). Run padpilot stop after editing so the daemon reloads on next use. Invalid types safely fall back to defaults and are reported by padpilot doctor.

{
  "brightness": 0.6,
  "rumble_scale": 0.5,
  "hook_approval_timeout_s": 45,
  "prompt_wheel": [
    "continue",
    "run the tests and fix failures",
    "explain what you just did",
    "stop and ask me first",
    "commit",
    "write tests for this",
    "summarise the changes",
    "keep fixing this bug"
  ],
  "mapping": {
    "triangle": ["text:continue, then run the tests", "act:submit"],
    "l3": "act:external_editor"
  },
  "sounds": {
    "enabled": true,
    "cues": { "done": "Glass", "permission": "Ping", "error": "Basso", "sounds_on": "Pop" }
  }
}

Supported mapping values (mapping and per-app profiles.<app>):

  • Semantic actions (recommended): act:submit, act:cancel, act:clear_input, act:cycle_mode, act:transcript, act:history_search, act:external_editor, act:interrupt, act:rewind, act:dictation, act:review, act:new_session, act:menu, act:prev_session, act:next_session, act:queue_submit, act:kill_agents, act:undo, act:model_picker, act:thinking. Append ? (e.g. act:clear_input?) to skip the step if the target app lacks that action.
  • Direct keys: enter, esc, tab, shift+tab, up, pageup, ctrl+<letter>, alt+<letter>, plus cmd+<letter> in the desktop app.
  • Literal text: text:your text here.
  • Built-ins: @cycle_focus, @battery, @toggle_lock, @retry, @choose:1..@choose:4, @brightness_up/down, @rumble_up/down, @idle_light, @sounds, @prev_session, @next_session, @none.
  • Action sequences: A list of any of the above, executed in order.

Commands

padpilot tutorial          # open the interactive Pad School page (enables practice mode while open)
padpilot manual            # open the bilingual manual in your browser
padpilot status            # controller, battery, and active sessions as JSON
padpilot keys              # print the resolved button layout for your current settings
padpilot desktop           # check macOS Accessibility permission and desktop status
padpilot watch --practice  # terminal practice mode: print every press and hold duration without sending keys
padpilot send "write a test"
padpilot press cross       # simulate a button press for debugging/scripts (never answers permission requests)
padpilot rumble success    # play a rumble pattern
padpilot doctor            # validate config, hidapi, controller, and daemon
padpilot stop              # stop the background daemon (restarts automatically when needed)
padpilot uninstall-codex   # remove Codex hooks

Slash commands in Claude Code: /padpilot:tutorial, /padpilot:status, /padpilot:demo, /padpilot:doctor, /padpilot:desktop.


Privacy & What padpilot Runs, Reads, and Writes

Everything runs locally on your machine. There is no server, no telemetry, and nothing from your sessions ever leaves your computer:

AreaDetails
Single DownloadOn first setup, padpilot creates ~/.padpilot/venv and installs hidapi==0.15.0 from PyPI. The tutorial and manual pages are served locally on 127.0.0.1:8737 (verifying localhost Host and Origin) with bundled OFL fonts—zero external requests.
Hooks & MemoryClaude Code / Codex events notify the daemon over a local Unix socket (~/.padpilot/daemon.sock). Your last prompt is held only in daemon RAM for R3 retry and never written to disk. Approval requests pass only a hash of the tool name and input.
Files Read1. The tail of the current session's transcript for token usage numbers only (to drive the 80% context warning; no message text is read or stored)
2. ~/.claude/keybindings.json and the dictation shortcut in Claude desktop's claude_desktop_config.json
3. ~/.padpilot/config.json
Files WrittenRestricted to ~/.padpilot/ (config.json, converted macOS system sounds in sounds/, socket/PID files, and daemon.log capped at 2×1 MB—typed text is logged by character length only, never content).
Keystrokes & MicOn macOS, Quartz CGEvent keystrokes are posted strictly to the frontmost Claude desktop app process, using the Accessibility API to focus the message input box (inspecting element roles/labels only, never text). The mic LED queries CoreAudio only to check whether any app is currently recording—padpilot never opens the microphone or records audio.

Troubleshooting & Development

  • Diagnostics: Run padpilot doctor or check ~/.padpilot/daemon.log and daemon.stderr.
  • Controller busy: Only one process on macOS can open the DualSense exclusively. Quit Steam or other controller remappers if the daemon cannot open the pad.
  • Preventing Apple's Games app from opening: The daemon opens the controller exclusively by default so macOS does not intercept the PS button. Set "share_controller": true in config.json if another app needs simultaneous access.
python3 -m unittest tests/test_core.py     # unit tests: protocol, controls, lights, state machine (no controller needed)
python3 tests/drive_wrapper.py             # PTY wrapper integration test with a fake agent
python3 tests/drive_claude.py [kitty]      # end-to-end test with real Claude Code
python3 tests/drive_codex.py               # end-to-end test with real Codex
python3 docs/make_logo.py docs/logo.svg    # regenerate the SVG banner
python3 docs/make_fonts.py FONT_DIR        # rebuild subsetted web fonts in padpilot/fonts/

License

MIT

// faq

What is padpilot?

Drive Claude Code, Codex and the Claude desktop app with a PS5 DualSense controller. It is open-source on GitHub.

Is padpilot free to use?

padpilot is open-source under the MIT license, so it is free to use.

What category does padpilot belong to?

padpilot is listed under education in the Claudeers registry of Claude-compatible tools.

0 views
★ 12 stars
unclaimed
updated about 7 hours ago

// embed badge

padpilot on Claudeers
[![Claudeers](https://claudeers.com/api/badge/padpilot.svg)](https://claudeers.com/padpilot)

// retro hit counter

padpilot hit counter
[![Hits](https://claudeers.com/api/counter/padpilot.svg)](https://claudeers.com/padpilot)

// reviews

// guestbook

0/500

// related in Education & Learning

🔓

Skills for Real Engineers. Straight from my .claude directory.

// educationmattpocock/⟨Shell⟩★ 327,486◷ MIT[ claude ]
🔓

Course to get into Large Language Models (LLMs) with roadmaps and Colab notebooks.

// educationmlabonne/★ 84,923◷ Apache-2.0[ claude ]
🔓

Learn it. Build it. Ship it for others.

// educationrohitg00/⟨Python⟩★ 79,059◷ MIT[ claude ]
🔓

DeepTutor: Agent-native Personalized Tutoring. https://deeptutor.info/.

// educationHKUDS/⟨Python⟩★ 58,346◷ Apache-2.0[ claude ]
→ see how padpilot connects across the ecosystem