How boccchi2993/locus-browser-agent-runtime works
Locus is a browser-local execution runtime for AI agents. A user submits a task through the workspace UI; the presentation store hands it to the agent harness, which coordinates model requests, approvals, and tool execution. The principal local execution path is bash through the compatibility shell into the VFS, Python worker, or network runtime. Workspace files, downloads, conversations, capabilities, and model replay state are handled by distinct subsystems. The README documents several capabilities beyond the sampled excerpts; links for those are included where the architecture is explicit, but uncertain internal wiring is omitted.
Main entry points: agent.js Agent session · store.js UI store · shell.js Compatibility shell · model-adapters.js Provider adapters
Components 24
Workspace UI
- Workspace interface
src/App.vue - UI store
src/ui/store.js - Event projector
src/ui/projector.js
Agent harness
- Agent session
src/agent.js - Model protocol
src/model.js - Provider adapters
src/model-adapters.js - Approval control
src/approval.js - Image attachments
src/attachments.js - Tool registry
src/tools.js
Browser substrate
- Compatibility shell
src/shell.js - Virtual filesystem
src/vfs.js - Workspace access
src/workspace.js - Python worker
src/shell.js - Network runtime
src/network.js - Execution telemetry
src/telemetry.js
State and extensions
- Capability composition
src/capabilities.js - Plugins and skills
src/extensions.js - Browser persistence
src/persistence.js
External services
- Public-resource relay
functions/fetch.js - Model API relay
functions/proxy.js
Other components
- User
- Model provider
- Browser APIs
- Pyodide
Connections 27
- User → Workspace interface: submits task
- Workspace interface → UI store: invokes actions
- UI store → Agent session: starts task
- Agent session → Model protocol: requests response
- Model protocol → Provider adapters: selects provider
- Provider adapters → Model provider: sends request
- Model provider → Provider adapters: returns response
- Provider adapters → Model API relay: relays request
- Agent session → Tool registry: dispatches tools
- Tool registry → Compatibility shell: runs bash
- Compatibility shell → Virtual filesystem: reads and writes
- Virtual filesystem → Workspace access: mounts folder
- Workspace access → Browser APIs: uses file access
- Compatibility shell → Python worker: executes Python
- Python worker → Pyodide: runs code
- Compatibility shell → Network runtime: runs curl
- Network runtime → Public-resource relay: relays request
- Agent session → Approval control: requests approval
- Approval control → UI store: updates pending state
- Agent session → Image attachments: uses image input
- Image attachments → Model protocol: provides image input
- UI store → Capability composition: enables capability
- Capability composition → Plugins and skills: composes extensions
- Agent session → Execution telemetry: records execution
- UI store → Event projector: projects events
- UI store → Browser persistence: stores session state
- Browser persistence → Browser APIs: uses IndexedDB and OPFS