Skip to content

Application Structure

Package Layout

codemol/
├── main.py                      # Entry point
├── codemol/
│   ├── __init__.py              # Lazy imports (MolbotWindow, main)
│   ├── app/                     # Core application
│   │   ├── window.py            # MolbotWindow — main UI + managers
│   │   ├── protocols.py         # AppContext Protocol
│   │   ├── command_dispatcher.py # Shortcuts, autocomplete list
│   │   ├── helpers.py           # _is_internal, _user_objects, _sel
│   │   ├── agent_manager.py     # AI agent integration
│   │   ├── atlas_manager.py     # Atlas/Nomosis API
│   │   ├── docking_manager.py   # GOLD docking results
│   │   ├── measurement_manager.py # Measurement registry UI
│   │   ├── scene_manager.py     # Timeline/scene management
│   │   ├── share_manager.py     # WebSocket shared sessions
│   │   ├── structure_manager.py # Multi-structure sidebar
│   │   └── ui_manager.py        # General UI helpers
│   ├── config/                  # User configuration
│   │   ├── alias_manager.py     # Command aliases
│   │   ├── config_manager.py    # ~/.codemol/config.json
│   │   ├── preset_manager.py    # Visual presets
│   │   └── session_manager.py   # Session save/load
│   ├── share/
│   │   └── server.py            # WebSocket relay server
│   ├── parser.py                # ParsedCommand, parse()
│   ├── tool_loader.py           # discover_tools(), dispatch()
│   ├── structure_session.py     # StructureSession
│   ├── console.py               # Terminal-style QTextEdit
│   ├── viewer.py                # 3D rendering widget
│   ├── theme.py                 # Catppuccin color palette
│   ├── selection_aliases.py     # Selection macro system
│   └── ...                      # Panels, tutorials, helpers
├── tools/                       # 27+ tool groups, 200+ tools
│   ├── io/
│   ├── measurements/
│   ├── representations/
│   └── ...
├── agents/                      # LLM agent system
│   ├── agent.py                 # run_agent() loop
│   ├── router.py                # Agent routing
│   ├── tool_bridge.py           # Tool schema generation
│   └── ...
├── tests/
└── resources/
    └── codemol.png              # App icon

Key Modules

main.py

Entry point. Creates QApplication, instantiates MolbotWindow, starts the event loop.

codemol/app/window.py

The central class: MolbotWindow(QMainWindow). This is the largest file (~1900 lines) and acts as the mediator connecting all managers, the viewer, the console, and the tool system.

Key responsibilities:

  • Creates the two-panel layout (viewer + console via QSplitter)
  • Instantiates all 8 domain managers + 4 config managers
  • Discovers tools at startup via discover_tools()
  • Handles commands via _handle_command(text)
  • Manages multi-structure state (scope, undo stack)
  • Implements keyboard shortcuts

codemol/parser.py

Parses raw command text into structured ParsedCommand objects:

@dataclass
class ParsedCommand:
    group: str       # "measurements"
    tool: str        # "distance"
    args: list[str]  # ["A/45/CA", "B/120/CA"]
    raw: str         # original text

codemol/tool_loader.py

Two critical functions:

  • discover_tools() — scans tools/ directory, returns nested dict of modules
  • dispatch() — executes a tool with argument fitting, alias resolution, and scoping

codemol/console.py

Terminal-style QTextEdit widget with:

  • Command history (up/down arrows)
  • Tab autocomplete
  • Syntax highlighting for output
  • Prompt management

codemol/viewer.py

Embeds OpenGL rendering into a Qt widget. Handles mouse events for rotation, zoom, translation, and atom picking.

codemol/theme.py

Catppuccin-inspired dark color palette used throughout the UI:

# Example colors from theme.py
BASE = "#1e1e2e"
MANTLE = "#181825"
TEXT = "#cdd6f4"
MAUVE = "#cba6f7"