feat: zsh: Add Hotkey Insertions hack

[bezhermoso]

Summary

Configure hotkeys to insert specific text into your command buffer, including cursor placement, which is highly useful for boilerplate commands.

What it achieves

• Map key sequences to insert literal text (macros)
• Control cursor placement with special characters (^B moves back, ^M executes)
• Reduce typing for frequently used commands

Zsh Configuration

# Git commit with cursor inside quotes
bindkey -s '^Xgc' 'git commit -m ""^B'

# Auto-execute git status
bindkey -s '^Xgs' 'git status^M'

# Find with cursor in pattern
bindkey -s '^Xfg' 'find . -name ""^B'

Special characters:

• ^B = Move cursor back
• ^M = Enter (auto-execute)
• ^A/^E = Beginning/End of line

Reference

• Original video: 10 Zsh Tips to Improve Productivity (15:19-16:50)

Additional Applications & Inspiration

• A User's Guide to the Z-Shell - Chapter 4
• Z-Shell Bindkeys Map
• Luca Scalzotto: Binding functions to hotkeys in ZSH
• An Introduction to the Z Shell - Bindings
• Mastering Zsh: Bindkey
• thevaluable.dev: Guide to the Zsh Line Editor
• The Geek Diary: bindkey Command Examples
• GitHub: tomsquest/dotfiles bindkey.zsh

[claude]

Code Review: Zsh Hotkey Insertions Feature

Summary

This PR adds excellent productivity features for Zsh, including hotkey insertions, command-line editing enhancements, and several quality-of-life improvements. The code is well-documented and follows the established patterns in the repository.

---

✅ Strengths

1. Excellent Documentation

• Each file has clear header comments explaining purpose, usage, and references
• Inline comments explain special characters and behavior
• Consistent with existing file patterns (e.g., inc.custom-widgets.zsh)
• Video references provide great context for learning

2. Code Quality

• Follows established patterns in the repository
• Proper use of Zsh bindkey and ZLE widgets
• Clean separation of concerns (one feature per file)
• Good use of autoload for edit-command-line

3. User Experience

• Commented-out examples allow easy customization
• Helpful tips sections in each file
• Special character reference tables are valuable
• Non-intrusive defaults (most bindings are examples)

---

🔍 Issues & Recommendations

1. Potential Conflict with Atuin (Medium Priority)

File: zsh/inc.magic-space.zsh:15

bindkey ' ' magic-space

Issue: Your .zshrc loads Atuin (line 75), which may override or conflict with the magic-space binding. Atuin typically binds space for its own history expansion.

Impact: Users might not get the expected magic-space behavior, or Atuin features might break.

Recommendation:

# Check if magic-space is compatible with your current setup
# If using Atuin, this binding may be overridden
# Consider testing: type "!!" then press space to verify expansion works
bindkey ' ' magic-space

Or move this file to load AFTER inc.atuin.zsh if you want Atuin to take precedence, and add a note about the conflict.

---

2. Keybinding Conflicts (Medium Priority)

File: zsh/inc.hotkey-insertions.zsh

Issue: Several Ctrl+X combinations might conflict with existing bindings:

• ^Xgc, ^Xga, etc. conflict with potential user customizations
• No check for existing bindings before overwriting

Recommendation: Add a conflict check section at the top:

# Check for existing keybinding conflicts
# Run: bindkey | grep '\^X' to see current Ctrl+X bindings
# Uncomment to see what's currently bound:
# bindkey | grep '\^X'

---

3. Cursor Movement in Docker Example (Low Priority)

File: zsh/inc.hotkey-insertions.zsh:37

bindkey -s '^Xde' 'docker exec -it  /bin/bash^B^B^B^B^B^B^B^B^B^B'

Issue: This uses 10 ^B characters to move the cursor back. This is fragile—if you change the command length, you need to recount the ^Bs.

Alternative approach: Use cursor positioning that's more maintainable:

bindkey -s '^Xde' 'docker exec -it ^A^F^F^F^F^F^F^F^F^F^F^F^F^F^F^F'  # Position after "docker exec -it "

Or consider using a ZLE widget instead for more complex cursor positioning:

docker-exec-widget() {
    LBUFFER='docker exec -it '
    RBUFFER=' /bin/bash'
}
zle -N docker-exec-widget
bindkey '^Xde' docker-exec-widget

This is more maintainable and clearer in intent.

---

4. Missing Error Handling (Low Priority)

File: zsh/inc.edit-command-line.zsh:11

autoload -Uz edit-command-line

Issue: No verification that autoload succeeded. If edit-command-line isn't available, the widget creation will fail silently.

Recommendation:

# Load the edit-command-line widget
if autoload -Uz edit-command-line 2>/dev/null; then
    zle -N edit-command-line
    bindkey '^X^E' edit-command-line
else
    print "Warning: edit-command-line widget not available" >&2
fi

---

5. Ordering Consideration (Low Priority)

File: zsh/.zshrc:80-89

The new includes are loaded in this order:

source_config "inc.edit-command-line.zsh"
source_config "inc.undo.zsh"
source_config "inc.magic-space.zsh"
source_config "inc.chpwd.zsh"
source_config "inc.suffix-aliases.zsh"
source_config "inc.global-aliases.zsh"
source_config "inc.zmv.zsh"
source_config "inc.named-directories.zsh"
source_config "inc.custom-widgets.zsh"
source_config "inc.hotkey-insertions.zsh"

Observation: inc.magic-space.zsh is loaded before inc.atuin.zsh (line 75 loads atuin). This means Atuin will likely override the space binding.

Recommendation: Either:

• Move these widget configs AFTER atuin if you want Atuin's behavior
• Move them BEFORE atuin if you want magic-space behavior
• Add clear documentation about which takes precedence

---

6. Named Directories - No Examples (Low Priority)

File: zsh/inc.named-directories.zsh

Observation: All examples are commented out. While this prevents unwanted behavior, users might not realize the feature exists without at least one working example.

Recommendation: Add one safe, universal example:

# Example: Quick access to dotfiles directory
hash -d dotfiles=~/.dotfiles

# Add your custom named directories below:

This gives users immediate value and demonstrates the feature.

---

🔒 Security Considerations

No security issues identified. The code:

• Doesn't execute external commands without user input
• Doesn't handle sensitive data
• Uses safe Zsh built-ins
• No injection vulnerabilities

---

⚡ Performance Considerations

Excellent performance characteristics:

• All features use native Zsh functionality (no external commands)
• Minimal startup overhead (just bindkey calls)
• No eval or subshells in the critical path
• Consistent with your optimization work documented in CLAUDE_ZSH_IMPROVEMENT_PLAN.md

---

🧪 Test Coverage

Observation: This repository doesn't appear to have automated tests for Zsh configurations.

Recommendation for future work:
Consider adding a basic test suite using zsh-test-runner or similar. Example tests:

# Test that hotkey insertions load without errors
source zsh/inc.hotkey-insertions.zsh
# Verify bindings exist
bindkey | grep '\^Xgc'

This is not required for this PR but would improve maintainability.

---

📋 Minor Suggestions

1. inc.undo.zsh:20 - The line bindkey '^_' undo is redundant since it's already the default. Consider removing it or adding a comment explaining it's for documentation purposes.

2. inc.magic-space.zsh:18 - The commented alternative binding example is helpful, but consider mentioning that it allows keeping both magic-space AND the normal space behavior.

3. inc.hotkey-insertions.zsh - The file is quite long (76 lines). Consider whether frequently-used personal hotkeys should be in a separate inc.hotkey-insertions.personal.zsh file that's gitignored, keeping only the examples in the committed version.

---

✅ Conclusion

This is a high-quality PR that adds valuable functionality while maintaining code quality and documentation standards. The issues identified are minor and mostly relate to potential conflicts with existing tools (Atuin) and edge cases.

Recommendation: Approve with minor changes

Priority fixes before merge:

1. Test magic-space behavior with Atuin and document any conflicts
2. Consider reordering includes to clarify precedence
3. Add conflict checking documentation for keybindings

Nice-to-have improvements:

• Error handling in edit-command-line
• Widget-based approach for complex hotkey insertions
• At least one working example in named-directories

Great work on the documentation and educational references! 🚀

[claude]

PR Review: feat: zsh: Add Hotkey Insertions hack

Summary

This PR adds a new Zsh configuration file for hotkey insertions using bindkey -s, allowing users to map key sequences to insert text with cursor placement control. Overall, this is a well-documented and useful addition to the dotfiles collection.

✅ Strengths

1. Excellent Documentation: The file header and inline comments are comprehensive and follow the existing patterns in the codebase (similar to inc.custom-widgets.zsh and inc.global-aliases.zsh)

2. Good Examples: Provides practical, real-world examples that demonstrate the feature effectively

3. Consistent Style: Follows the established conventions:

   • File naming: inc.*.zsh pattern
   • Comment structure with reference links
   • Proper sourcing in .zshrc

4. Safe Defaults: Commented out potentially destructive/environment-specific bindings (SSH, Kubernetes, etc.)

⚠️ Issues Found

1. CRITICAL: Keybinding Conflicts

The new file creates conflicts with existing keybindings in inc.custom-widgets.zsh:

Conflicts:

• ^Xd - Conflicted between:

  • inc.hotkey-insertions.zsh:31 → git diff
  • inc.custom-widgets.zsh:32 → insert-date widget

• ^Xc - Conflicted between:

  • inc.hotkey-insertions.zsh:35 → docker compose
  • inc.custom-widgets.zsh:77 → copy-command-to-clipboard widget

• ^Xl - Potential conflict:

  • inc.hotkey-insertions.zsh:40 → ls -lah^M
  • inc.custom-widgets.zsh:25 → clear-history-keep-buffer widget

• ^Xs - Conflicted between:

  • inc.hotkey-insertions.zsh:30 → git status^M
  • inc.custom-widgets.zsh:43 → prepend-sudo widget

Impact: These conflicts will cause the later-loaded file (inc.hotkey-insertions.zsh) to override the existing custom widgets, breaking functionality users may rely on.

Recommendation: Use different key combinations to avoid conflicts. Suggestions:

• Use a different prefix (e.g., ^G for git commands, ^D for docker)
• Use three-character sequences (e.g., ^Xgg for git commands, ^Xdd for docker)
• Document the conflict resolution strategy

2. Code Quality Issues

a) Inefficient cursor positioning in inc.hotkey-insertions.zsh:37

bindkey -s '^Xde' 'docker exec -it  /bin/bash^B^B^B^B^B^B^B^B^B^B'

Problem: Using 10 ^B characters to move cursor back is fragile and hard to maintain. If the command changes, the count becomes incorrect.

Better approach: Use ^A (beginning of line) or ^E (end of line) combined with forward movement when possible, or use a custom widget instead.

b) Similar issue in inc.hotkey-insertions.zsh:46

bindkey -s '^Xrg' 'rg "" .^B^B^B'

Problem: Magic number of ^B repetitions - not immediately clear why 3 is needed.

Suggestion: Add a comment explaining the cursor positioning, e.g.:

bindkey -s '^Xrg' 'rg "" .^B^B^B'  # Cursor inside quotes (3 back from end)

3. Inconsistency in Command Patterns

Some commands auto-execute with ^M, others don't. The logic isn't always clear:

• ^Xgs → git status^M - auto-executes (read-only, safe)
• ^Xgp → git push - doesn't auto-execute (destructive, good)
• ^Xll → ls -lah^M - auto-executes (read-only, safe)
• ^Xcd → cd ..^M - auto-executes (state-changing, questionable)

Recommendation: Add a comment explaining the decision criteria for auto-execution vs manual execution.

4. Missing Error Handling

Unlike inc.global-aliases.zsh which checks for command availability:

if command -v jq &> /dev/null; then
    alias -g JSON='| jq .'
fi

The new file doesn't verify that commands like rg, docker, git exist before binding them.

Recommendation: While not critical for dotfiles (user controls their environment), consider adding optional guards or documenting the dependencies.

5. Documentation Gap

The file doesn't explain the relationship/difference between:

• bindkey -s (this file) for simple text insertion
• bindkey + zle -N (custom-widgets.zsh) for complex actions

Recommendation: Add a note explaining when to use each approach.

🔒 Security Considerations

✅ No security issues found. The code:

• Doesn't execute arbitrary commands automatically (except safe read-only ones)
• Doesn't handle sensitive data
• Doesn't introduce injection vulnerabilities

🚀 Performance Considerations

✅ No performance concerns. The file:

• Only defines static keybindings
• Has minimal overhead (loads once on shell startup)
• Doesn't use expensive operations

🧪 Test Coverage

⚠️ No tests exist in the repository for any zsh configurations. This is typical for dotfiles, but worth noting:

• Manual testing required after changes
• No automated validation of keybinding conflicts
• No syntax checking in CI/CD

Recommendation: Consider adding basic zsh syntax validation to CI (e.g., zsh -n <file> to check syntax).

📝 Suggested Changes

High Priority

1. Resolve keybinding conflicts - Must fix before merge
2. Document conflict resolution strategy - Add comments about why specific keys were chosen

Medium Priority

3. Improve cursor positioning code - Replace magic ^B counts with clear patterns
4. Add decision rationale - Document when commands auto-execute vs don't

Low Priority

5. Add relationship documentation - Explain bindkey -s vs custom widgets
6. Consider command guards - Optional availability checks

🎯 Verdict

Conditional Approval - This is a useful feature with excellent documentation, but the keybinding conflicts must be resolved before merging. Once conflicts are addressed, this will be a valuable addition to the dotfiles.

---

Great work on the comprehensive documentation and practical examples! The referenced video tutorial and additional resources are particularly helpful. 👍

[claude]

Pull Request Review: Hotkey Insertions Feature

Summary

This PR adds a useful feature for creating shell command macros using bindkey -s, allowing users to insert boilerplate commands with cursor positioning. The implementation is well-documented and follows the repository's established patterns.

Code Quality: ⭐⭐⭐⭐⭐

Strengths:

• Excellent documentation with clear examples and references
• Follows existing conventions perfectly (matches inc.custom-widgets.zsh and inc.global-aliases.zsh style)
• Comprehensive comments explaining special character syntax
• Well-organized with logical grouping (git, docker, common commands, etc.)
• Educational value with commented-out examples for various use cases
• Properly integrated into .zshrc in alphabetical order

Observations:

• File structure and formatting are consistent with other inc.*.zsh files
• Header comment block provides clear usage instructions
• Special character syntax documentation is thorough and helpful

Potential Issues: ⚠️

1. Key Binding Conflicts (Medium Priority)

The PR introduces several ^X prefix bindings that conflict with existing bindings in inc.custom-widgets.zsh:

Conflicts:

• ^Xd - New: insert-date widget (inc.custom-widgets.zsh:32) vs. Git diff shortcut (this PR)
• ^Xc - New: copy-command-to-clipboard widget (inc.custom-widgets.zsh:77) vs. Git commit shortcut (this PR)
• ^Xl - New: clear-history-keep-buffer widget (inc.custom-widgets.zsh:25) vs. Git log shortcut (this PR)
• ^Xs - New: prepend-sudo widget (inc.custom-widgets.zsh:43) vs. Git status shortcut (this PR)
• ^Xq - New: quote-command widget (inc.custom-widgets.zsh:52) (no conflict currently)

Impact: Since inc.hotkey-insertions.zsh is sourced AFTER inc.custom-widgets.zsh (line 84 vs 85 in .zshrc), the new bindings will silently override the existing widgets, breaking functionality users may already rely on.

Recommendation: Use a different prefix or two-character sequences to avoid conflicts:

• Option 1: Use ^Xg prefix for git commands (e.g., ^Xgc for git commit - already done!)
• Option 2: Use different single letters after ^X that don't conflict
• Option 3: Document the conflicts and intentional overrides if that's the desired behavior

2. Git Command Shortcuts May Behave Unexpectedly (Low Priority)

Lines 27, 29, 37-38: Auto-executing commands with \n can be dangerous if users accidentally trigger them:

bindkey -s '^Xgs' $'git status\n'  # Auto-executes immediately
bindkey -s '^Xgl' $'git log --oneline -10\n'  # Auto-executes immediately
bindkey -s '^Xll' $'ls -lah\n'  # Auto-executes immediately
bindkey -s '^Xcd' $'cd ..\n'  # Auto-executes immediately

Recommendation: Consider removing the \n suffix to allow users to review before executing, or document this behavior prominently as it differs from the other shortcuts.

3. Docker Exec Cursor Positioning (Minor Issue)

Line 34: Using multiple \cb characters for cursor positioning is fragile:

bindkey -s '^Xde' $'docker exec -it  /bin/bash\cb\cb\cb\cb\cb\cb\cb\cb\cb\cb'

If the command structure changes or spaces are adjusted, this breaks. This is somewhat unavoidable with bindkey -s, but worth noting.

Recommendation: Consider using a custom widget (like in inc.custom-widgets.zsh) for more complex cursor positioning needs, or accept this limitation and document it.

Performance Considerations: ✅

• No performance concerns
• bindkey -s operations are lightweight and execute at shell initialization
• No loops, external commands, or heavy operations

Security Concerns: ✅

• No security issues identified
• All commands are user-triggered and transparent
• Auto-executing commands (\n suffix) could be considered a minor UX issue but not a security concern
• No command injection risks or unsafe practices

Test Coverage: ⚠️

Observation: This is a dotfiles repository with no automated tests, which is typical for this type of project.

Manual Testing Recommendations:

1. Test each binding in both emacs and vi keymaps (if applicable)
2. Verify control characters work correctly after fix in commit 4cbd776
3. Test key binding conflicts with existing widgets
4. Verify cursor positioning with various terminal emulators

Additional Observations:

Positive:

1. Excellent commit messages - Both commits have clear, descriptive messages explaining what changed and why
2. Educational documentation - Extensive references and learning resources
3. Extensibility - Clear section for users to add custom bindings
4. Platform awareness - No platform-specific issues (control chars work cross-platform)

Suggestions:

1. Consider adding a note at the top of the file about potential conflicts with inc.custom-widgets.zsh
2. The example on line 19 uses uppercase ^XGC while actual bindings use lowercase (e.g., ^Xgc) - consider clarifying the case-sensitivity behavior
3. Consider grouping related two-character sequences (e.g., all ^Xg* for git) for better discoverability

Recommendation: ✅ Approve with Suggestions

This is a solid, well-implemented feature that adds real value. The main issue is the key binding conflicts that should be resolved before merging. Otherwise, the code quality is excellent and follows repository conventions perfectly.

Suggested Action Items:

1. Resolve key binding conflicts with inc.custom-widgets.zsh (HIGH priority)
2. Consider removing auto-execute \n suffix from some commands or document the behavior prominently (MEDIUM priority)
3. Clarify the case-sensitivity example discrepancy (LOW priority)

Great work on the implementation and documentation! 🎉

[claude]

Review: Hotkey Insertions Feature

Summary: This PR introduces a well-designed hotkey insertion system for Zsh that allows binding key sequences to insert boilerplate commands with intelligent cursor placement. The implementation is clean, well-documented, and follows the repository conventions.

STRENGTHS:

Code Quality:

• Excellent documentation with extensive inline comments explaining the ZLE buffer model
• Clear examples in both comments and commit messages
• Consistent style following repository naming conventions (inc.*.zsh pattern)
• Educational value teaching users about Zsh internals

Design Decisions:

• Smart vi-mode compatibility fix moving from ^B control characters to ZLE widgets with {CURSOR} markers (commit aeb1581)
• Proper separation of concerns moving date insertion from inc.custom-widgets.zsh
• Fixed the ^Xd keybinding conflict between date insertion and docker commands
• Reusable helper function _insert_with_cursor() is well-designed and DRY

Integration:

• Seamlessly integrated into .zshrc source chain at zsh/.zshrc:85
• Non-breaking changes that moved existing functionality without breaking it

ISSUES AND RECOMMENDATIONS:

1. Security Concerns:

Command injection risk in _insert_with_cursor (line 44-50):
While current usage is safe (all calls use literal strings), the function does not validate input. Consider adding a warning comment about only using with literal strings, not user input.

Docker exec defaults to /bin/bash (line 67):
Many containers use /bin/sh instead of /bin/bash (Alpine-based images). Consider changing to /bin/sh for better portability, or document this limitation, or create two shortcuts.

2. Potential Bugs:

Date insertion may behave differently on systems:
The date command at line 77 may vary between macOS (BSD) and Linux (GNU). While +%Y-%m-%d is standard, consider adding error handling.

Keybinding conflicts not documented:
The PR introduces many new ^X* bindings. While ^Xd conflict was fixed, there is no systematic check for conflicts with other inc.*.zsh files or zinit plugins. Recommendation: Add a comment section listing all bindings for easy reference.

3. Performance Considerations:

Negligible performance impact - implementation is efficient:

• Widget functions are lazy-loaded only when invoked
• String operations are simple parameter expansions
• No external commands except in _hotkey_insert_date

4. Code Quality:

Function naming: Using underscore prefix is correct for private/internal functions per Zsh conventions. Consider documenting this.

Missing function documentation: While file header is excellent, individual widget functions lack docstrings.

5. Test Coverage:

No automated tests - consider adding manual test checklist:

• Test in emacs mode: bindkey -e
• Test in vi mode: bindkey -v
• Verify no conflicts: bindkey | grep "^X"
• Test each hotkey manually

6. Documentation:

Missing documentation about:

• These bindings override any existing ^X* bindings
• Bindings with ^M (auto-execute) can be dangerous if misconfigured
• How to unbind/override specific hotkeys

Consider adding troubleshooting section with commands like: bindkey | grep "^X", bindkey -r "^Xgc", zle -la | grep hotkey

BEST PRACTICES:

Things done well:

• Moving date insertion to fix ^Xd conflict shows good debugging
• Comprehensive commented examples for future customization
• Reference links to external resources
• Using bindkey -s for simple cases, ZLE widgets for complex ones

Suggestions:

1. Consider adding way to disable specific hotkey groups (via zstyle or env vars)
2. Add function to list all active hotkey bindings
3. Consider making hotkey prefix configurable (default ^X but allow override)

SECURITY ASSESSMENT: Low Risk

• No external command execution with unsanitized input
• No file system operations
• All inputs are literal strings in the code
• General warning about bindkey -s with ^M (auto-execute) applies

OVERALL ASSESSMENT: APPROVE with minor suggestions

This is high-quality work that:

• Solves a real problem (reducing typing for common commands)
• Is well-documented and educational
• Follows repository conventions
• Has thoughtful fix for vi-mode compatibility
• Maintains backward compatibility

The issues raised are mostly minor suggestions for enhancement rather than blocking problems. The code is production-ready as-is.

Suggested next steps:

1. Consider adding keybinding reference comment
2. Add note about Docker /bin/bash limitation
3. Maybe add troubleshooting section
4. Consider documenting how users can customize the ^X prefix

Great work! This is a valuable addition to the dotfiles.

---

Review generated by Claude Code