How lalamss/botx works
BotX is a VS Code extension paired with an Electron desktop companion. The main workflow observes workspace activity, turns events into observations and context, analyzes problems, chooses an intervention, and presents guidance through VS Code or the avatar. The README documents this runtime flow; source-index references and excerpts support several internal calls. Some capabilities are documented but their implementation wiring was not sampled, so those relationships are omitted or marked unverified.
Main entry points: aiExplanationEngine.ts Explanation Agent · diagnosticPipeline.ts Diagnostic Pipeline · sensors Workspace Sensors · decisionEngine.ts Decision Agent
Components 21
Workspace Observation
- Extension Runtime
robot-brain/src/extension.ts - Workspace Sensors
robot-brain/src/sensors - Event Filtering
robot-brain/src/eventFilter - Diagnostic Pipeline
robot-brain/src/pipeline/diagnosticPipeline.ts
ACES Reasoning
- Perception Agent
robot-brain/src/perception/perceptionEngine.ts - Context Agent
robot-brain/src/context/contextEngine.ts - Decision Agent
robot-brain/src/decision/decisionEngine.ts - Learning Profile
robot-brain/src/learning/learningAgent.ts
Developer Assistance
- Explanation Agent
robot-brain/src/explanation/aiExplanationEngine.ts - Gemini AI
robot-brain/src/ai/gemini.ts - Quick Fix Actions
robot-brain/src/ui/botxCodeActionProvider.ts - Environment Guardian
robot-brain/src/sensors/environmentSensor.ts - API Deprecation Scan
robot-brain/src/sensors/importInspector.ts - Git Conflict Resolver
robot-brain/src/explanation/gitConflictEngine.ts - Stuck Detection
robot-brain/src/pipeline/stuckDetectionPipeline.ts
Desktop Companion
- Behaviour FSM
robot-brain/src/behaviour/behaviourController.ts - Motion Planner
robot-brain/src/motion/motionPlanner.ts - WebSocket Server
robot-brain/src/utils/websocketServer.ts - Electron Companion
robot-body/main.js
Other components
- Developer
- VS Code Host
Connections 23
- Developer → VS Code Host: uses
README.md - VS Code Host → Extension Runtime: activates
README.md - Extension Runtime → Workspace Sensors: starts
robot-brain/src/extension.ts - Workspace Sensors → Event Filtering: publishes events
robot-brain/src/wiring/eventSubscriptionManager.ts - Event Filtering → Perception Agent: feeds events
README.md - Perception Agent → Context Agent: provides observations
README.md - Diagnostic Pipeline → Context Agent: builds context
robot-brain/src/pipeline/diagnosticPipeline.ts - Diagnostic Pipeline → Explanation Agent: requests analysis
robot-brain/src/pipeline/diagnosticPipeline.ts - Context Agent → Explanation Agent: supplies context
README.md - Explanation Agent → Gemini AI: requests reasoning
robot-brain/src/explanation/aiExplanationEngine.ts - Explanation Agent → Decision Agent: informs intervention
- Decision Agent → Behaviour FSM: selects behaviour
README.md - Behaviour FSM → Motion Planner: plans motion
robot-brain/src/behaviour/behaviourController.ts - Behaviour FSM → WebSocket Server: sends actions
robot-brain/src/behaviour/behaviourController.ts - WebSocket Server → Electron Companion: streams state
README.md - Electron Companion → Developer: shows guidance
README.md - Diagnostic Pipeline → Quick Fix Actions: registers fixes
robot-brain/src/pipeline/diagnosticPipeline.ts - Developer → Quick Fix Actions: invokes fix
README.md - Workspace Sensors → Environment Guardian: checks workspace
- Workspace Sensors → API Deprecation Scan: scans imports
- Explanation Agent → Git Conflict Resolver: resolves conflicts
- Diagnostic Pipeline → Stuck Detection: detects repeated issues
- Decision Agent → Learning Profile: uses profile