CLAUDE.md - QMK Development (Keychron Q5 Max)

Guidelines and commands for the customized Keychron Q5 Max firmware project based on the wireless_playground fork.

Project Scope

Origin: git.rootiest.dev/rootiest/qmk_firmware
Upstream: github.com/Keychron/qmk_firmware (branch: wireless_playground)
Primary Keyboard: Keychron Q5 Max (ANSI Encoder)
Development Workflow: Work is performed on the q5_dev branch before merging to main.
Feature Goals: Tap-Dance, expanded layers, advanced Chording, Unicode support, and Auto-correct.

Build and Flash Commands

All commands must be run from the root of the repository inside the project Python virtual environment. The system qmk is not used — activate the venv first:

source .venv/bin/activate

Every qmk command below assumes the venv is active (or prefix each with source .venv/bin/activate &&).

Compilation

# Build the Q5 Max ANSI Encoder firmware
qmk compile -kb keychron/q5_max/ansi_encoder -km via

Flashing

# Flash the Q5 Max (requires the board to be in bootloader mode)
qmk flash -kb keychron/q5_max/ansi_encoder -km via

Environment Setup

# Ensure the submodules are up to date (critical for the wireless_playground branch)
git submodule update --init --recursive

# Set the default keyboard/keymap
qmk setup
qmk config user.keyboard=keychron/q5_max/ansi_encoder
qmk config user.keymap=via

Code Style and Patterns

Keymap Structure: Keep the keymap.c organized by layers. Use descriptive defines for layer names (e.g., _BASE, _FN, _CHORD).
Feature Modules: For advanced features like Chording or Tap-Dance, prefer creating separate headers/source files in the keymap folder to keep keymap.c readable.
Firmware Size: Monitor the compiled .bin size, as wireless features and large feature sets (like Auto-correct) can quickly fill up flash memory.
Documentation: Comment any complex chording logic or non-standard Tap-Dance implementations to ensure maintainability.

Development Workflow

Verify the current branch is q5_dev.
Implement features in keyboards/keychron/q5_max/ansi_encoder/keymaps/via/.
Test compilation locally before committing.
Ensure rules.mk has the necessary flags enabled (e.g., TAP_DANCE_ENABLE = yes, UNICODE_ENABLE = yes).

Git Conventions

Use conventional commits (feat:, fix:, docs:, chore:, etc.) scoped to the keyboard where relevant (e.g. feat(q5_max):).
Do not include Co-Authored-By: Claude trailers in commit messages.

Chained / Stacked PRs

When merging a chain of PRs (e.g. A → main, B → A, C → B), always delete the branch after each merge. Gitea (and GitHub) will automatically retarget any open PRs pointing at the deleted branch to the branch it was merged into. This keeps the chain collapsing cleanly into main without manual retargeting or cleanup PRs.

3.0 KiB Raw Blame History