How zoecyber001/ghost-shell works
Ghost-Shell is a desktop chess-playing bot: the user chooses a side and supplies opponent moves, while the app detects the board, selects a move with Stockfish, previews it, and clicks it into the chess UI. main.py coordinates the game loop and chess position; vision, engine, humanizer, and overlay provide distinct runtime stages. Source excerpts show these direct calls; the README documents the HUD and humanized interaction, and the tree does not include an assets directory, so the Stockfish executable is represented as an external dependency.
Main entry points: main.py Game loop · engine.py Move engine · humanizer.py Humanized input · vision.py Board vision
Components 12
Game orchestration
- Game loop
main.py - Chess position
main.py
Board perception
- Board vision
core/vision.py
Move decision
- Move engine
core/engine.py
Screen interaction
- Humanized input
core/humanizer.py - Move HUD
ui/overlay.py
Runtime support
- Configuration
utils/config.py - Logging
utils/logger.py
Other components
- Player
- Desktop screen
- Stockfish
- Desktop mouse
Connections 17
- Player → Game loop: chooses side, enters moves
- Game loop → Board vision: finds board, detects side
- Board vision → Desktop screen: captures screen
- Game loop → Board vision: waits for changes
- Game loop → Chess position: updates position
- Game loop → Move engine: requests move
- Move engine → Stockfish: queries candidate moves
- Game loop → Move HUD: previews move
- Game loop → Humanized input: executes move
- Humanized input → Desktop mouse: moves and clicks
- Game loop → Configuration: reads settings
- Move engine → Configuration: reads settings
- Humanized input → Configuration: reads settings
- Game loop → Logging: logs game events
- Board vision → Logging: logs detection
- Move engine → Logging: logs engine events
- Humanized input → Logging: logs actions