Skip to content

feat: manage cmux and karabiner with nix - #874

Merged
keito4 merged 5 commits into
mainfrom
codex/nix-cmux-karabiner
Jun 22, 2026
Merged

feat: manage cmux and karabiner with nix#874
keito4 merged 5 commits into
mainfrom
codex/nix-cmux-karabiner

Conversation

@keito4

@keito4 keito4 commented Jun 21, 2026

Copy link
Copy Markdown
Owner

Summary

  • add home-manager modules for cmux and Karabiner configuration
  • install cmux through the nix-darwin Homebrew cask list
  • preserve Caps Lock as Control and scope cmux IME shortcuts to cmux only
  • document the environment-management decision in ADR 0014

Verification

  • nix fmt ./home/cmux.nix ./home/karabiner.nix ./home/default.nix ./modules/homebrew.nix
  • nix eval --raw '.#darwinConfigurations.keitos-MacBook-Pro.config.home-manager.users.keito.home.file.".config/karabiner/karabiner.json".text'
  • nix eval --raw '.#darwinConfigurations.keitos-MacBook-Pro.config.home-manager.users.keito.home.file.".config/cmux/config".text'
  • nix eval --json '.#darwinConfigurations.keitos-MacBook-Pro.config.homebrew.casks'
  • npm test -- --runTestsByPath test/nix-darwin-config.test.js test/config-validation.test.js
  • npm run format:check
  • npm run lint

Summary by CodeRabbit

  • New Features
    • Added declarative configuration for terminal multiplexing and keyboard/IME behavior (cmux, Ghostty rendering, and Karabiner remaps scoped to the cmux app).
    • Added an overwrite-on-rebuild “portable dotfiles” setup via Home Manager.
    • Added a managed command to collect local “secret-looking” config file inventory without reading file contents.
    • Updated Homebrew casks (including adding cmux and adjusting the development/productivity/communication set).
  • Documentation
    • Added ADRs for keyboard/terminal configuration and portable dotfile management.
  • Tests
    • Extended Jest coverage to validate generated configuration content, file placement, and wiring for these setups.

@coderabbitai

coderabbitai Bot commented Jun 21, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 02fd52da-cbed-43d8-bad9-71d5735a32a7

📥 Commits

Reviewing files that changed from the base of the PR and between d083ca1 and 11ecc5b.

📒 Files selected for processing (5)
  • nix/home/agent-commands.nix
  • nix/home/default.nix
  • nix/modules/homebrew.nix
  • script/agent/collect-local-configs.sh
  • test/nix-darwin-config.test.js

📝 Walkthrough

Walkthrough

Adds two Home Manager modules (cmux.nix and karabiner.nix) for terminal and input management with JIS keyboard and cmux-scoped IME shortcuts, introduces dotfiles and agent-commands modules for portable configuration management, registers a cmux Homebrew cask, generates declarative config files, and validates with a Jest test suite and two ADRs (0014, 0015).

Changes

cmux and Karabiner Home Manager Management

Layer / File(s) Summary
Homebrew cmux cask and cmux Home Manager module
nix/modules/homebrew.nix, nix/home/cmux.nix
Adds "cmux" to the Homebrew casks array. Creates cmux.nix that builds cmux application configuration (schema, quit/workspace/socket/browser/notification/sidebar/terminal behavior with ripgrep path) and ghostty settings (font/UI/scrollback), then writes ~/.config/cmux/config (empty), ~/.config/cmux/cmux.json (serialized config), and ~/.config/ghostty/config via home.file with force = true.
Karabiner config generation and key remapping
nix/home/karabiner.nix
Defines bundle-identifier condition for com.cmuxterm.app, a helper for conditional basic key remappings, and full karabinerConfig (JIS virtual keyboard, caps_lockleft_control, complex modification parameters, IME shortcut remaps for j, semicolon, quote scoped to cmux bundle). Writes config as JSON to ~/.config/karabiner/karabiner.json with force = true and trailing newline.
Module imports, tests, and ADR decision
nix/home/default.nix, test/nix-darwin-config.test.js, docs/adr/0014-manage-cmux-karabiner-with-home-manager.md
Wires cmux.nix and karabiner.nix into home-manager imports. Adds Jest assertions validating Home Manager imports, Homebrew casks, cmux config content (no C-j/C-Semicolon), cmux app defaults, ghostty font/sizing/scrollback, and Karabiner JSON with cmux IME shortcuts. Records decision in ADR 0014 specifying that darwin-rebuild switch is the source of truth and home-manager overwrites manual edits.

Portable Dotfiles and Infrastructure Management

Layer / File(s) Summary
ADR 0015 and dotfiles.nix module structure
docs/adr/0015-manage-portable-user-dotfiles-with-home-manager.md, nix/home/dotfiles.nix
Documents in ADR 0015 the decision to manage portable (non-secret) dotfiles via Home Manager using force = true to claim ownership, specifying included sources (zsh/AeroSpace/tool configs) and excluded artifacts (SSH, tokens, cloud auth, databases). Implements nix/home/dotfiles.nix with managedSource helper and maps home-relative paths to tracked sources under ../../dot/.
Agent local config collection script and Home Manager wiring
nix/home/agent-commands.nix, script/agent/collect-local-configs.sh, test/nix-darwin-config.test.js
Adds agent-commands.nix Home Manager module installing the agent config collector at ~/.local/bin/agent-collect-local-configs. Introduces Bash script that inventories local/secret-looking config files without reading contents: accepts --root and --output arguments, classifies by filename pattern, records size/mtime via stat with platform fallbacks, and outputs TSV with category, bytes, mtime, path. Jest test validates script exists/is executable and that home-manager wiring is correct.
AeroSpace window manager keybindings and layout
dot/aerospace.toml
Adds complete AeroSpace configuration with startup/login, UI normalization, layout defaults, focus-follow-mouse, macOS unhide-apps, qwerty key mapping, and gap sizes. Defines [mode.main.binding] for layout switching, focus/move/resize, numeric/lettered workspace navigation, node movement, workspace back-and-forth, monitor movement with wrap, and service mode transition. Defines [mode.service.binding] for reload-config, layout/tree reset, tiling/floating toggle, close windows, join-splits, and volume controls.
Tool configs and shell environment updates
dot/config/act/actrc, dot/config/agent-deck/config.toml, dot/config/codespaces-secrets/repos.txt, dot/config/graphite/aliases, .zsh/configs/virtual/go.zsh, .zsh/configs/virtual/php.zsh, .zsh/configs/virtual/python.zsh
Adds act Docker image platform mappings for Ubuntu runners, agent-deck tool defaults/global search/logs/instance settings, codespaces repository identifiers, graphite alias documentation and examples. Updates shell environment configs to indicate go/python moved to dev containers and set LDFLAGS/CPPFLAGS for Homebrew PHP 7.4.
Test infrastructure and dotfiles coverage validation
test/nix-darwin-config.test.js
Adds Jest file reader utility and validates nix/home/default.nix imports all four new Home Manager modules. Validates nix/home/dotfiles.nix manages expected dotfile paths by existence check and explicitly excludes credential/host/auth markers (user_config, hosts.yml, .npmrc, .ssh, .env.secret) to ensure secrets remain unmanaged.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Home Manager claims the dotfiles today,
Nix builds the keybindings—now you can play!
AeroSpace windows dance, JIS keys aligned,
Karabiner and cmux, both perfectly designed.
Portable configs flow through the rebuild,
The rabbit's declarative dream fulfilled! ✨

Possibly related PRs

  • keito4/config#612: Establishes the nix-darwin/home-manager foundation by introducing nix/home/default.nix and nix/modules/homebrew.nix; this PR directly extends those modules by adding cmux.nix and karabiner.nix to the default imports and updating the Homebrew casks list.

Suggested labels

released

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check ❓ Inconclusive The PR description covers the main changes and verification steps but does not follow the provided template structure with required sections like 'Why', 'What', 'How to test', and 'Checklist'. Restructure the description to match the template with clear 'Why', 'What', 'How to test' sections and complete the 'Checklist' items.
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title 'feat: manage cmux and karabiner with nix' clearly summarizes the main change of adding Nix-based configuration management for cmux and Karabiner tools.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/nix-cmux-karabiner

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

test/nix-darwin-config.test.js

Oops! Something went wrong! :(

ESLint: 10.5.0

ReferenceError: describe is not defined
at Object. (/test/eslint-config.test.js:35:1)
at Module._compile (node:internal/modules/cjs/loader:1830:14)
at Object..js (node:internal/modules/cjs/loader:1961:10)
at Module.load (node:internal/modules/cjs/loader:1553:32)
at Module._load (node:internal/modules/cjs/loader:1355:12)
at wrapModuleLoad (node:internal/modules/cjs/loader:255:19)
at loadCJSModuleWithModuleLoad (node:internal/modules/esm/translators:326:3)
at ModuleWrap. (node:internal/modules/esm/translators:231:7)
at ModuleJob.run (node:internal/modules/esm/module_job:437:25)
at async node:internal/modules/esm/loader:639:26


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@claude

claude Bot commented Jun 21, 2026

Copy link
Copy Markdown
Contributor

Claude finished @keito4's task in 0s —— View job


I'll analyze this and get back to you.

@keito4 keito4 self-assigned this Jun 21, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2412b7c92c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread nix/home/cmux.nix
Comment on lines +4 to +6
home.file.".config/cmux/config" = {
force = true;
text = "";

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Configure the cmux file that is actually read

cmux's configuration docs list ~/.config/ghostty/config for terminal settings and ~/.config/cmux/cmux.json for cmux-owned settings (https://cmux.com/docs/configuration), so this generated .config/cmux/config is not read. On machines where Ghostty/cmux already has keybinds for Ctrl+Shift+J/;/'—the case this module is meant to neutralize—darwin-rebuild leaves those bindings in place and the IME shortcuts can still be consumed by the terminal; manage the Ghostty config or cmux.json instead.

Useful? React with 👍 / 👎.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
docs/adr/0015-manage-portable-user-dotfiles-with-home-manager.md (1)

27-31: 💤 Low value

Reduce repetition of "Source" at sentence beginnings.

Lines 27-31 have three successive sentences beginning with "Source," which impacts readability. Consider rephrasing one or more sentences to vary the structure.

📝 Suggested revision
 - Source reusable zsh config fragments and functions from the repository.
-- Source AeroSpace configuration from `dot/aerospace.toml`.
-- Source small workflow-tool configs for act, Agent Deck, Graphite aliases, and
-  Codespaces secret repository selection.
+- Manage AeroSpace configuration from `dot/aerospace.toml`.
+- Include small workflow-tool configs for act, Agent Deck, Graphite aliases, and
+  Codespaces secret repository selection.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/adr/0015-manage-portable-user-dotfiles-with-home-manager.md` around
lines 27 - 31, Lines 27-31 contain repetitive sentence structures with multiple
bullet points beginning with "Source," which reduces readability. Rephrase one
or more of these bullet points to vary the sentence structure while maintaining
the same meaning. For example, you could restructure the bullets describing zsh
config fragments, AeroSpace configuration, workflow-tool configs, and git ignore
and peco configuration to use different opening words or sentence constructions
such as "Include," "Incorporate," "Load," or restructure them as compound
phrases to improve the overall flow and readability of the list.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@dot/aerospace.toml`:
- Around line 1-2: The header comments on lines 1-2 of aerospace.toml
incorrectly instruct users to manually copy and edit the file at
~/.aerospace.toml, but this file is actually declaratively managed and
force-overwritten by Home Manager configuration in nix/home/dotfiles.nix.
Replace these misleading comments with new header text that clearly states the
file is managed by Home Manager and directs users to modify their configuration
through the Home Manager nix files instead of editing the dotfile manually.

---

Nitpick comments:
In `@docs/adr/0015-manage-portable-user-dotfiles-with-home-manager.md`:
- Around line 27-31: Lines 27-31 contain repetitive sentence structures with
multiple bullet points beginning with "Source," which reduces readability.
Rephrase one or more of these bullet points to vary the sentence structure while
maintaining the same meaning. For example, you could restructure the bullets
describing zsh config fragments, AeroSpace configuration, workflow-tool configs,
and git ignore and peco configuration to use different opening words or sentence
constructions such as "Include," "Incorporate," "Load," or restructure them as
compound phrases to improve the overall flow and readability of the list.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ff3c03e4-52b7-41ba-bba8-ab92a972cee9

📥 Commits

Reviewing files that changed from the base of the PR and between 2412b7c and d083ca1.

📒 Files selected for processing (14)
  • .zsh/configs/virtual/go.zsh
  • .zsh/configs/virtual/php.zsh
  • .zsh/configs/virtual/python.zsh
  • docs/adr/0014-manage-cmux-karabiner-with-home-manager.md
  • docs/adr/0015-manage-portable-user-dotfiles-with-home-manager.md
  • dot/aerospace.toml
  • dot/config/act/actrc
  • dot/config/agent-deck/config.toml
  • dot/config/codespaces-secrets/repos.txt
  • dot/config/graphite/aliases
  • nix/home/cmux.nix
  • nix/home/default.nix
  • nix/home/dotfiles.nix
  • test/nix-darwin-config.test.js
✅ Files skipped from review due to trivial changes (7)
  • dot/config/graphite/aliases
  • .zsh/configs/virtual/php.zsh
  • .zsh/configs/virtual/python.zsh
  • .zsh/configs/virtual/go.zsh
  • dot/config/codespaces-secrets/repos.txt
  • dot/config/act/actrc
  • docs/adr/0014-manage-cmux-karabiner-with-home-manager.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • nix/home/default.nix

Comment thread dot/aerospace.toml
Comment on lines +1 to +2
# Place a copy of this config to ~/.aerospace.toml
# After that, you can edit ~/.aerospace.toml to your liking

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Update the header comments to match Home Manager ownership.

Line 1 and Line 2 currently tell users to copy/edit ~/.aerospace.toml manually, but this file is declaratively managed and force-overwritten by Home Manager (nix/home/dotfiles.nix Line 4-Line 7 and Line 11). Please replace this guidance to prevent confusing, non-persistent manual edits.

Suggested edit
-# Place a copy of this config to ~/.aerospace.toml
-# After that, you can edit ~/.aerospace.toml to your liking
+# Managed by Home Manager via nix/home/dotfiles.nix
+# Edit this repository file and apply with darwin-rebuild/home-manager switch
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# Place a copy of this config to ~/.aerospace.toml
# After that, you can edit ~/.aerospace.toml to your liking
# Managed by Home Manager via nix/home/dotfiles.nix
# Edit this repository file and apply with darwin-rebuild/home-manager switch
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dot/aerospace.toml` around lines 1 - 2, The header comments on lines 1-2 of
aerospace.toml incorrectly instruct users to manually copy and edit the file at
~/.aerospace.toml, but this file is actually declaratively managed and
force-overwritten by Home Manager configuration in nix/home/dotfiles.nix.
Replace these misleading comments with new header text that clearly states the
file is managed by Home Manager and directs users to modify their configuration
through the Home Manager nix files instead of editing the dotfile manually.

@keito4
keito4 merged commit ce7995e into main Jun 22, 2026
17 checks passed
@keito4
keito4 deleted the codex/nix-cmux-karabiner branch June 22, 2026 01:07
@claude claude Bot mentioned this pull request Jun 26, 2026
@github-actions

github-actions Bot commented Jul 4, 2026

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 1.119.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

released リリース済み

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant