Helix Keybindings Trainer

Interactive terminal trainer for mastering Helix editor keybindings through hands-on practice.

Features

• 🎮 Interactive Learning - Practice Helix commands in real scenarios
• 📊 Performance Scoring - Get rated on efficiency (Perfect/Excellent/Good/Fair/Poor)
• 💡 Smart Hints - Progressive hints when you need help
• 🎯 Optimal Solutions - Learn the most efficient way to solve each task
• 📴 100% Offline - No internet required, all data stored locally
• 🔒 Privacy-First - No telemetry, tracking, or data collection

Installation

From Source

git clone https://github.com/bug-ops/helix-trainer.git
cd helix-trainer
cargo build --release
./target/release/helix-trainer

Requirements

• Rust 1.70 or higher
• Terminal with unicode support

Quick Start

cargo run --release

Controls:

• Menu: ↑/↓ or j/k to navigate, Enter to select scenario
• Training: Use Helix commands (h,j,k,l,dd,x,etc.), F1 for hints, Esc to quit
• Results: r to retry, m for menu, q to quit

Supported Commands

Currently supports 14 core Helix commands:

Movement: h, j, k, l, w, b, e, 0, $, gg, G Editing: x (delete char), dd (delete line), i (insert mode) Undo: u (undo), Ctrl-r (redo)

Scenarios

Training scenarios are defined in TOML format:

[[scenarios]]
id = "delete_line_001"
name = "Delete current line"
description = "Delete the line where cursor is located"

[scenarios.setup]
file_content = "line 1\nline 2\nline 3"
cursor_position = [1, 0]

[scenarios.target]
file_content = "line 1\nline 3"
cursor_position = [1, 0]

[scenarios.scoring]
optimal_count = 1
max_points = 100
tolerance = 0

See scenarios/basic.toml for examples.

Development

# Run tests
cargo test --lib

# Check code quality
cargo clippy --all-targets -- -D warnings

# Format code
cargo fmt

# Run with debug logging
RUST_LOG=debug cargo run

Architecture

Built with:

• TUI: ratatui - Terminal UI framework
• Editor: helix-core - Official Helix primitives
• Config: serde + toml - Scenario format

Implementation Status:

• ✅ Stage 1: Foundation (TUI, game engine, scoring)
• ✅ Stage 2: Helix Integration (simulator, commands, visualization)
• 🔄 Stage 3: Polish (statistics, export, custom scenarios)

Contributing

Contributions welcome! We follow a feature branch workflow with pull requests.

See CONTRIBUTING.md for detailed guidelines.

Quick Start:

# Create feature branch
git checkout -b feature/your-feature

# Make changes and test
cargo nextest run --lib
cargo +nightly fmt
cargo clippy -- -D warnings
cargo deny check

# Push and create PR
git push origin feature/your-feature

CI Checks:

• Tests on Linux, macOS, Windows (cargo-nextest)
• Formatting (rustfmt nightly)
• Lints (clippy)
• Security audit (cargo-deny)

License

MIT License - see LICENSE for details.

Acknowledgments

• Helix Editor - For the amazing editor
• Ratatui - For the TUI framework
• Inspired by vim-tutor and other interactive learning tools

Roadmap

• More scenarios (intermediate, advanced)
• Statistics and progress tracking
• Custom scenario editor
• Export/import progress
• Additional Helix commands
• Tutorial mode for beginners