How ian688/modus works
Modus is a local Python agent runtime with CLI and Electron/Web desktop interfaces. The main workflow is a user task entering through a UI, being managed as a bounded run, routed through an agent mode, and executed through governed tools; results and run events are persisted for review and replay. Major documented branches include MOA, Peri, external agent runtimes, browser automation, and the desktop preview workspace. Some subsystems are represented from README capabilities and the source index; their internal call paths were not sampled.
Main entry points: server.py Desktop Server · executor.py Tool Executor · controller.py Run Controller · registry.py Tool Registry
Components 24
User Interfaces
- Electron Shell
electron/main.js - Desktop Server
src/modus/desktop/server.py - CLI
src/modus/entrypoints/cli.py
Run Orchestration
- Run Controller
src/modus/runtime/controller.py - Run Budget
src/modus/runtime/budget.py - Run State
src/modus/runtime/state.py - Completion Gate
src/modus/desktop/completion_gate.py
Agent Modes
- Query Engine
src/modus/agent/query_engine.py - Default Runner
src/modus/desktop/default_runner.py - MOA Runner
src/modus/desktop/moa_runner.py - Peri Runner
src/modus/desktop/peri_runner.py - External Runner
src/modus/desktop/external_runner.py
Tools and Safety
- Tool Registry
src/modus/tools/registry.py - Tool Executor
src/modus/tools/executor.py - Tool Definitions
src/modus/tools/base.py - Approval Policy
src/modus/policy/approval.py - Browser Runtime
electron/browser-runtime.js - MCP Client
src/modus/mcp_client.py
Desktop Services
- Run Database
src/modus/desktop/db.py - Preview Host
electron/renderer/preview/preview-host.ts - Preview Adapters
electron/renderer/preview/adapters/browser-preview.ts - Model Discovery
src/modus/desktop/model_discovery.py - Configuration
src/modus/config.py
Other components
- User
Connections 28
- User → Electron Shell: uses desktop
README.md - User → CLI: runs tasks
README.md - Electron Shell → Desktop Server: starts and checks
electron/main.js - Desktop Server → Default Runner: routes runs
src/modus/desktop/server.py - Desktop Server → MOA Runner: routes runs
src/modus/desktop/server.py - Desktop Server → Peri Runner: routes runs
src/modus/desktop/server.py - Desktop Server → External Runner: routes runs
src/modus/desktop/server.py - CLI → Query Engine: runs queries
- Default Runner → Run Controller: shares run controls
- Run Controller → Run State: guards lifecycle
src/modus/runtime/controller.py - Run Controller → Run Budget: shares run limits
src/modus/runtime/controller.py - Run Controller → Completion Gate: checks completion
src/modus/runtime/controller.py - Desktop Server → Run Database: persists run data
src/modus/desktop/server.py - Query Engine → Tool Registry: supplies tools
src/modus/agent/query_engine.py - Tool Registry → Tool Definitions: registers tools
src/modus/tools/registry.py - Tool Executor → Tool Definitions: executes handlers
src/modus/tools/executor.py - Tool Executor → Tool Registry: resolves tools
src/modus/tools/executor.py - Tool Executor → Run Budget: checks budget
src/modus/tools/executor.py - Tool Executor → Approval Policy: requests approval
src/modus/tools/executor.py - Desktop Server → Model Discovery: supports model setup
src/modus/desktop/server.py - Desktop Server → Configuration: loads settings
src/modus/desktop/server.py - Desktop Server → Preview Host: offers preview workspace
- Preview Host → Preview Adapters: mounts adapters
- Electron Shell → Browser Runtime: starts browser runtime
electron/main.js - Browser Runtime → Tool Executor: serves browser tools
- Tool Registry → MCP Client: registers MCP tools
- Desktop Server → Run Database: records approvals
README.md - Desktop Server → Run Database: records events
README.md