{"id":51495939,"url":"https://github.com/daniel-pittman/rubiks-cube-solver","last_synced_at":"2026-07-07T15:30:28.328Z","repository":{"id":360535187,"uuid":"1048670870","full_name":"daniel-pittman/rubiks-cube-solver","owner":"daniel-pittman","description":"A repository detailing my attempt to \"vibe code\" a graphical Rubik's Cube solver with different LLMs","archived":false,"fork":false,"pushed_at":"2026-07-07T03:14:07.000Z","size":1539,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-07-07T05:07:02.582Z","etag":null,"topics":["ai-collaboration","claude-code","cli","flask","opengl","pyside6","python","rubiks-cube","solver","three-js"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daniel-pittman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T20:40:49.000Z","updated_at":"2026-07-02T19:36:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/daniel-pittman/rubiks-cube-solver","commit_stats":null,"previous_names":["daniel-pittman/rubiks-cube-solver"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/daniel-pittman/rubiks-cube-solver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-pittman%2Frubiks-cube-solver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-pittman%2Frubiks-cube-solver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-pittman%2Frubiks-cube-solver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-pittman%2Frubiks-cube-solver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daniel-pittman","download_url":"https://codeload.github.com/daniel-pittman/rubiks-cube-solver/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-pittman%2Frubiks-cube-solver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35234127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-collaboration","claude-code","cli","flask","opengl","pyside6","python","rubiks-cube","solver","three-js"],"created_at":"2026-07-07T15:30:25.259Z","updated_at":"2026-07-07T15:30:28.179Z","avatar_url":"https://github.com/daniel-pittman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/social-preview.png\" alt=\"Rubik's Cube Solver — A Human-AI Collaboration Case Study\" width=\"800\"\u003e\n\u003c/p\u003e\n\n# Rubik's Cube Solver\n\n**A Case Study in Human-AI Collaborative Software Development**\n\n[![CI](https://github.com/daniel-pittman/rubiks-cube-solver/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/daniel-pittman/rubiks-cube-solver/actions/workflows/ci.yml)\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub release](https://img.shields.io/github/v/release/daniel-pittman/rubiks-cube-solver)](https://github.com/daniel-pittman/rubiks-cube-solver/releases)\n\n---\n\n## 📖 Table of Contents\n\n- [What Is This Project?](#-what-is-this-project)\n- [The AI Development Story](#-the-ai-development-story)\n- [Quick Start](#-quick-start)\n- [Features](#-features)\n- [Architecture](#-architecture)\n- [What We Learned](#-what-we-learned)\n- [Development Journey](#-development-journey)\n- [Technical Details](#-technical-details)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n---\n\n## 🎯 What Is This Project?\n\nThis is a **fully-functional Rubik's Cube solver** with three different interfaces (command-line, web, and desktop), built **entirely through conversation with Claude Code**, Anthropic's AI coding assistant.\n\n**The goal?** To explore what's possible when humans and AI collaborate on complex software development, and to document the process so others can learn from it.\n\n### Key Facts\n\n- **100% of code generated by AI** (Claude Code)\n- **Zero lines written directly by human** (except this README update!)\n- **Complete working application** with 3D visualization, solving algorithms, and multiple UIs\n- **Full documentation** of every prompt, decision, and iteration\n- **Production-quality code** meeting professional standards (9.07/10 pylint score, 28 passing tests)\n\nThis project serves as a **real-world case study** for:\n- What LLMs can do well (and where they struggle)\n- How to effectively guide AI coding assistants\n- The balance between AI capability and human direction\n- Building production-quality software through natural language\n\n---\n\n## 🤖 The AI Development Story\n\n### What Went Well\n\n**✅ Algorithm Implementation**\n- Claude Code successfully implemented complex cube mechanics using matrix transformations\n- Built a plugin-based solver architecture with IDDFS (Iterative Deepening Depth-First Search)\n- Created accurate 3D visualizations using Three.js and OpenGL\n\n**✅ Multiple UI Paradigms**\n- Command-line interface with ANSI colors and interactive REPL\n- Web interface with real-time WebSocket communication\n- Desktop application with hardware-accelerated OpenGL rendering\n\n**✅ Code Quality \u0026 Testing**\n- 28 comprehensive unit and integration tests (all passing)\n- Consistent 9.0+ pylint scores throughout development\n- Clean architecture with proper separation of concerns\n\n**✅ Documentation**\n- Self-documenting code with comprehensive docstrings\n- Detailed inline comments explaining complex logic\n- Configuration files with explanatory headers\n\n### Where Human Guidance Was Critical\n\n**🧠 Architecture Decisions**\n- Choosing the plugin-based solver system\n- Deciding on the hybrid face-clicking + camera-dragging interaction model\n- Structuring the project into phases (Core → Solver → CLI → Web → Desktop)\n\n**🧠 Problem-Solving**\n- Debugging cube rotation mechanics (initial implementation had incorrect edge cycling)\n- Fixing animation timing issues (colors updating before vs. after animations)\n- Resolving OpenGL context issues with face click detection\n\n**🧠 UX Design**\n- Making the desktop app non-blocking by moving solver to background thread\n- Implementing \"smart drag detection\" to distinguish clicks from camera movements\n- Choosing accessible color contrasts (WCAG AA compliance)\n\n### What Didn't Work (At First)\n\n**❌ Initial Cube Implementation**\n- First attempt at cube moves had incorrect edge cycling for 5 out of 6 moves\n- Required complete rewrite following proven matrix transformation approach\n- **Lesson**: Start with proven approaches for complex algorithms\n\n**❌ Animation Synchronization**\n- Multiple attempts needed to get cube colors updating at the right time during animations\n- Issue: Understanding when to save state (before move) vs. when to animate (after move)\n- **Lesson**: State management in animations requires careful sequencing\n\n**❌ Face Click Detection**\n- Initial OpenGL picking implementation caused GLError (invalid operation)\n- Root cause: Calling glReadPixels outside rendering context\n- **Lesson**: Framework constraints (like OpenGL contexts) need explicit handling\n\n### The Process\n\nDevelopment followed an **incremental, phase-based approach**:\n\n1. **Phase 1**: Core cube mechanics (505 lines, 32 tests)\n2. **Phase 2**: Solver system with plugin architecture (664 lines)\n3. **Phase 3**: CLI interface with colored terminal (650+ lines)\n4. **Phase 4**: Web interface with 3D visualization\n5. **Phase 5**: Desktop application with OpenGL rendering\n\nEach phase was completed **100%** before moving to the next. When bugs were found, we went back and fixed them properly rather than moving forward with technical debt.\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n**You need Python installed.** Here's how to check and install:\n\n```bash\n# Check if Python is installed (need 3.11 or higher)\npython3 --version\n\n# If not installed:\n# - macOS: Install from python.org or use `brew install python3`\n# - Linux: `sudo apt install python3` or `sudo yum install python3`\n# - Windows: Download from python.org and run installer\n```\n\n### Installation \u0026 Running\n\n**The easiest way: Use the launcher script**\n\n```bash\n# Clone the repository\ngit clone https://github.com/daniel-pittman/rubiks-cube-solver.git\ncd rubiks-cube-solver\n\n# Run the launcher (handles everything automatically!)\n./run_app.sh\n```\n\nThe launcher will:\n1. Create a Python virtual environment\n2. Install all dependencies\n3. Show you a menu to choose which interface to run\n\n**Menu options:**\n1. **CLI** - Command-line interface with colored cube display\n2. **Web** - Flask server with 3D visualization (opens browser to localhost:5001)\n3. **Desktop** - PySide6 application with OpenGL 3D rendering\n4. **Tests** - Run all 28 unit tests to verify everything works\n\n### Manual Installation (Alternative)\n\n```bash\n# Create virtual environment\npython3 -m venv venv\n\n# Activate it\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install the project. Pick the extras you need:\n#   .[web]       — Flask + Socket.IO for the web interface\n#   .[desktop]   — PySide6 + PyOpenGL for the desktop interface\n#   .[all]       — both web and desktop runtime extras\n#   .[dev]       — linters + pytest (add this if you'll be contributing)\npip install -e \".[all]\"\n\n# Run specific interface\npython -m solver.cli              # Command-line\npython -m solver.flask_app        # Web (then open localhost:5001)\npython -m solver.desktop_app      # Desktop GUI\n```\n\n---\n\n## ✨ Features\n\n### 🧊 Core Functionality\n\n- **Accurate Cube Mechanics**: Matrix-based state using proven transformation approach\n- **IDDFS Solver**: Finds optimal solutions for scrambled cubes (depth 5-8)\n- **Plugin Architecture**: Extensible solver system for future algorithms\n- **Move Notation**: Standard Western notation (R, L, U, D, F, B, primes, doubles)\n- **State Management**: Save and restore scrambled states for solution replay\n\n### 🖥️ Command-Line Interface\n\n```\n\u003e scramble 5\n🎲 Scrambling cube with 5 moves...\nMoves: R U' F D L\n\n\u003e solve\n🧠 Solving cube...\nSolution found: L' D' F' U R'\n[Step-by-step playback with colored visualization]\n\n\u003e help\n[Comprehensive interactive help system]\n```\n\n**Features**:\n- Colored ANSI terminal output (cross-platform)\n- Interactive REPL with command history\n- Manual move execution or sequence input\n- Step-by-step solution visualization\n- Undo/redo functionality\n\n### 🌐 Web Interface\n\n**Launch**: `python -m solver.flask_app` → Open `http://localhost:5001`\n\n**Interactive 3D Controls**:\n- **Left-click face**: Clockwise rotation\n- **Right-click face**: Counter-clockwise\n- **Ctrl/Cmd+Click**: 180° rotation\n- **Drag background**: Rotate camera view\n- **Scroll**: Zoom in/out\n- **Auto-rotate button**: Continuous rotation for viewing\n- **Reset camera**: Return to default angle\n\n**Features**:\n- Real-time 3D cube with Three.js\n- Smart drag detection (knows click vs drag)\n- Live move history panel\n- Solution generation and playback\n- Save/restore scrambled states\n- WebSocket real-time updates\n- Mobile-responsive touch controls\n\n### 🖼️ Desktop Application\n\n**Launch**: `python -m solver.desktop_app`\n\n**Features**:\n- Hardware-accelerated OpenGL rendering\n- Interactive face clicking (same controls as web)\n- Smooth rotation animations with easing\n- Background solver thread (UI stays responsive)\n- Solution playback dialog with manual controls\n- Camera orbit controls\n\n---\n\n## 🏗️ Architecture\n\n### Project Structure\n\n```\nsolver/\n├── core/                      # Core cube logic\n│   ├── cube.py               # Cube implementation (505 lines)\n│   ├── solver.py             # Solver interface (186 lines)\n│   ├── solvers/              # Plugin system\n│   │   ├── base_solver.py   # Abstract base (232 lines)\n│   │   └── iddfs_solver.py  # IDDFS algorithm (246 lines)\n│   └── tests/               # 28 unit tests\n│       ├── test_cube.py\n│       ├── test_cube_comprehensive.py\n│       └── test_scramble.py\n├── cli/                      # Command-line interface\n│   ├── cli_app.py           # Interactive CLI (650+ lines)\n│   └── __main__.py          # Entry point\n├── web/                      # Web interface\n│   ├── static/\n│   │   ├── css/styles.css   # Responsive styling\n│   │   └── js/\n│   │       ├── cube3d.js    # Three.js visualization\n│   │       ├── socket-client.js  # WebSocket sync\n│   │       ├── ui-controls.js    # Interactive controls\n│   │       └── app.js            # Main app logic\n│   └── templates/\n│       └── index.html        # Single-page app\n├── desktop/                  # Desktop application\n│   ├── cube_gl_widget.py    # OpenGL 3D widget\n│   └── __init__.py\n├── flask_app.py             # Flask + SocketIO server\n├── desktop_app.py           # PySide6 main window\n└── tests/                   # Integration tests\n    └── test_solver_integration.py\n```\n\n### Technology Stack\n\n| Component | Technology |\n|-----------|-----------|\n| **Backend** | Python 3.11+, Flask, Flask-SocketIO |\n| **Frontend** | Vanilla JavaScript, Three.js, Socket.IO |\n| **Desktop** | PySide6 (Qt6), PyOpenGL |\n| **Core Logic** | NumPy for array operations |\n| **Testing** | pytest (28 tests, 100% pass rate) |\n| **Code Quality** | black, isort, autoflake, pylint (9.07/10) |\n| **Version Control** | Git with pre-commit hooks |\n\n### Key Design Patterns\n\n1. **Plugin Architecture**: Solvers register themselves; runtime selection\n2. **State Preservation**: Save cube state before solving for replay\n3. **Event-Driven UI**: WebSocket for web, Qt signals for desktop\n4. **Hybrid Interaction**: Seamless blending of face clicks + camera controls\n5. **Background Processing**: Threading for solver to keep UI responsive\n\n---\n\n## 🎓 What We Learned\n\n### About AI-Assisted Development\n\n**LLMs Excel At:**\n- Implementing well-defined algorithms from specifications\n- Generating boilerplate and repetitive code structures\n- Writing comprehensive tests and documentation\n- Following consistent code styles and patterns\n- Applying design patterns (plugins, facades, etc.)\n\n**Humans Are Essential For:**\n- High-level architecture decisions\n- Debugging subtle interaction issues\n- UX design and accessibility considerations\n- Recognizing when to restart vs. iterate\n- Deciding when \"good enough\" is actually good enough\n\n**The Sweet Spot:**\n- Human provides vision, direction, and judgment\n- AI implements, tests, and documents\n- Human reviews, guides refinement, and maintains quality bar\n- Iterative back-and-forth until solution emerges\n\n### About Rubik's Cube Solvers\n\n**Technical Insights:**\n- Matrix transformations are cleaner than position tracking\n- Edge cycling is the tricky part (not face rotation)\n- IDDFS works well for small scrambles (5-8 moves)\n- State explosion makes depth \u003e10 impractical without heuristics\n- Animation timing requires careful state management\n\n**UX Insights:**\n- Hybrid click+drag mode feels more natural than mode switching\n- Accessibility (color contrast, keyboard support) matters\n- Background processing is critical for complex solvers\n- Solution playback needs manual controls, not just auto-play\n\n---\n\n## 📚 Development Journey\n\nThis project was built through **~300+ conversational exchanges** over several sessions. Key milestones:\n\n### Phase 1: Core Cube (September 2025)\n- Initial attempt had incorrect edge cycling\n- Complete rewrite using matrix transformation approach\n- 32 unit tests, all moves validated mathematically\n- **Learning**: Start with proven approaches for complex algorithms\n\n### Phase 2: Solver System (September 2025)\n- Designed plugin architecture for extensibility\n- Implemented IDDFS optimal solver\n- Created solver registry and auto-selection\n- **Learning**: Good architecture pays off later\n\n### Phase 3: CLI Interface (September 2025)\n- Rich terminal UI with ANSI colors\n- Interactive REPL with command history\n- Cross-platform compatibility handling\n- **Learning**: User experience matters even in CLI\n\n### Phase 4: Web Interface (September 2025)\n- Multiple iterations on interaction model\n- Discovered hybrid click+drag approach\n- Fixed animation synchronization issues\n- **Learning**: UX iteration is essential, even with AI\n\n### Phase 5: Desktop Application (October 2025)\n- Implemented hardware-accelerated OpenGL rendering\n- Solved UI freezing with background threads\n- Fixed OpenGL context issues with face clicking\n- **Learning**: Framework constraints require explicit handling\n\n### Phase 6: Post-Launch Features (October 2025+)\n- **Scramble Reveal**: Show scramble sequence in competition format\n- Copy to clipboard functionality\n- Spoiler text in move log (click-to-reveal)\n- Responsive design refinements\n- **Learning**: Rapid feature iteration based on user feedback\n\n**Complete development log**: See [conversation_summary/](conversation_summary/) for every prompt and response organized by phase.\n\n---\n\n## 🔬 Technical Details\n\n### Cube Representation\n\nUses 3D NumPy array: `stickers[6 faces][3 rows][3 columns]`\n\n```python\n# Each face is a 3x3 grid of colors\nstickers[Face.U] = [[W, W, W],\n                    [W, W, W],\n                    [W, W, W]]\n```\n\n**Color Scheme** (Western/WCA standard):\n- White (U) ↔ Yellow (D)\n- Red (R) ↔ Orange (L)\n- Green (F) ↔ Blue (B)\n\n### Move Execution\n\nStandard notation: `R`, `L`, `U`, `D`, `F`, `B`\n- Prime (`'`): Counter-clockwise\n- Double (`2`): 180°\n\nImplementation:\n1. Rotate the face itself (`np.rot90`)\n2. Cycle edge pieces between adjacent faces\n3. Reverse appropriate edges for correct orientation\n\n### IDDFS Solver\n\n**Algorithm**: Iterative Deepening Depth-First Search\n- Searches depth 1, then 2, then 3, etc.\n- Guarantees optimal solution (fewest moves)\n- Practical limit: depth 8 (~5-10 seconds)\n\n**Optimization**: Prunes redundant moves (e.g., no `R` after `R'`)\n\n### Web Architecture\n\n**Client-Server Communication**:\n```\nBrowser (Three.js) ←→ SocketIO ←→ Flask ←→ Cube Core\n```\n\n**State Sync**:\n1. User action (click, scramble, solve)\n2. Client emits WebSocket event\n3. Server updates cube state\n4. Server broadcasts state to all clients\n5. Clients update 3D visualization\n\n### Testing Strategy\n\n**28 Tests covering**:\n- Individual move correctness (6 tests)\n- Mathematical properties (3 tests)\n- Scramble validity (7 tests)\n- Solver integration (6 tests)\n- Edge cases (6 tests)\n\n**Run tests**: `./run_app.sh` → Select option 4\n\n---\n\n## 🤝 Contributing\n\nThis project welcomes contributions! Areas of interest:\n\n### Enhancement Ideas\n- **Additional Solvers**: Implement A*, IDA*, or Kociemba's algorithm\n- **Performance**: Optimize IDDFS with pattern databases\n- **Features**: Cube timer, move counter, solution comparison\n- **UI/UX**: Improved animations, themes, tutorials\n\n### Development Setup\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run `./run_python_formatters.sh` (must score ≥9.0/10)\n5. Run tests: `pytest solver/ -v`\n6. Submit pull request\n\n**Code Standards**:\n- Black formatting (auto-applied)\n- Pylint score ≥9.0\n- Type hints where helpful\n- Comprehensive docstrings\n- Unit tests for new functionality\n\n---\n\n## 📖 Additional Documentation\n\n- **[CLAUDE.md](CLAUDE.md)**: Instructions for continuing development with Claude Code\n- **[DEVELOPMENT_JOURNAL.md](DEVELOPMENT_JOURNAL.md)**: Retrospective from Claude's perspective with technical architecture and lessons learned\n- **[conversation_summary/](conversation_summary/)**: Complete conversation history organized by development phase\n\n---\n\n## 📄 License\n\nMIT License - See [LICENSE](LICENSE) for details\n\nCopyright (c) 2025 Daniel Pittman\n\n---\n\n## 🙏 Acknowledgments\n\n- **MagicCube** ([github.com/trincaog/magiccube](https://github.com/trincaog/magiccube)): Reference for cube mechanics\n- **Three.js**: 3D visualization library\n- **Flask \u0026 Socket.IO**: Real-time web framework\n- **PySide6**: Qt6 Python bindings\n- **Anthropic**: Claude Code AI coding assistant\n\n---\n\n## 💬 Reflections on AI-Assisted Development\n\nThis project demonstrates that LLMs can build **production-quality software** when given proper guidance. But it's not magic—it's collaboration.\n\n**What surprised us**:\n- How quickly complex features came together with good prompts\n- The importance of incremental development (don't skip phases!)\n- How much human judgment matters for architecture and UX\n- That AI-generated code can meet professional quality standards\n\n**What we'd do differently**:\n- Start with even more research on cube mechanics\n- Build a test suite *before* implementing features\n- Document architectural decisions as we make them\n- Create a git branching strategy earlier\n\n**The bottom line**: AI coding assistants are powerful tools that amplify human developers, not replace them. The human provides vision, judgment, and direction. The AI provides implementation speed, consistency, and tireless iteration.\n\n---\n\n**Built through conversation between** 🧠 Human Guidance + 🤖 Claude Code\n\n*Want to see the complete development conversation? Check out [conversation_summary/](conversation_summary/)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-pittman%2Frubiks-cube-solver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniel-pittman%2Frubiks-cube-solver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-pittman%2Frubiks-cube-solver/lists"}