How jsmastery-pro/jsm-hq works
JSM HQ is a local control plane for a team of coding agents: a person configures a project and team, asks the lead to plan work, then monitors worker sessions, tasks, terminals, access requests, and pull requests in a pixel-art office. The server coordinates planning, workspaces, sandbox or local execution, GitHub review synchronization, and agent messaging; the browser consumes live office data and renders the UI and scene. README documents these product stages and capabilities. Server wiring beyond shown imports is summarized conservatively; unsampled subsystem links are omitted where their callers are not evidenced.
Main entry points: main.ts Server runtime · sessions.ts Agent sessions · hub.ts Team hub · App.tsx HQ browser UI
Components 29
HQ Control Plane
- HQ launcher
bin/jsm-hq.mjs - Server runtime
server/main.ts - Team hub
server/hub.ts - HQ state
server/store.ts - Task planning
server/planner.ts - Action items
server/actionItems.ts - Agent messaging
server/inbox.ts - HTTP and live feed
server/http.ts
Agent Execution
- Agent sessions
server/sessions.ts - Agent workspaces
server/workspace.ts - Terminal backends
server/backends/pty.ts - Sandbox control
server/sbx.ts - Setup checks
server/setup.ts - Repository operations
server/repo.ts
Workflow Integrations
- GitHub review sync
server/githubSync.ts - Agent MCP tools
server/mcp.ts - Stack and skills
src/data/stack.ts
Office Client
- HQ browser UI
src/App.tsx - Office data store
src/store/office.ts - Data source contract
src/data/source.ts - Agent and task drawers
src/ui/drawers/AgentDrawer.tsx - Terminal view
src/ui/drawers/TerminalView.tsx - Project settings
src/ui/settings/StackSettings.tsx
Office Rendering
- Office scene
src/office/OfficeScene.ts - Office layout
src/office/layout/layout.ts - Office and UI state
src/store/office.ts - Visual theme
src/office/engine/palette.ts - Theme tokens
src/theme/tokens.ts
Other components
- Project owner
Connections 31
- Project owner → HQ launcher: starts HQ
- HQ launcher → Server runtime: launches
bin/jsm-hq.mjs - Server runtime → Team hub: creates
server/main.ts - Server runtime → HTTP and live feed: starts
server/main.ts - Server runtime → GitHub review sync: starts sync
server/main.ts - Server runtime → Task planning: wires
server/main.ts - Server runtime → Agent messaging: wires
server/main.ts - Server runtime → Action items: wires
server/main.ts - Team hub → HQ state: reads and writes
server/hub.ts - Team hub → Repository operations: uses repo
server/hub.ts - Team hub → Task planning: exports plan
server/hub.ts - Agent sessions → Agent workspaces: prepares folder
server/sessions.ts - Agent sessions → Terminal backends: selects backend
server/sessions.ts - Agent sessions → Setup checks: runs checks
server/sessions.ts - Agent sessions → Sandbox control: queries sandbox
server/sessions.ts - Agent sessions → Stack and skills: installs skills
server/sessions.ts - GitHub review sync → Team hub: syncs PR state
- Project owner → HQ browser UI: configures and monitors
- HQ browser UI → Office data store: connects
src/App.tsx - Office data store → Data source contract: uses contract
src/store/office.ts - Office data store → HTTP and live feed: streams updates
- Office data store → Server runtime: sends commands
- HQ browser UI → Agent and task drawers: hosts drawers
src/App.tsx - Agent and task drawers → Terminal view: renders terminal
src/ui/drawers/AgentDrawer.tsx - Project settings → Stack and skills: configures stack
- HQ browser UI → Office scene: renders canvas
src/App.tsx - Office scene → Office layout: builds scene layout
src/office/OfficeScene.ts - Office scene → Office and UI state: reads state
src/office/OfficeScene.ts - Office scene → Visual theme: draws with
src/office/OfficeScene.ts - Office layout → Visual theme: uses palette
src/office/layout/layout.ts - Visual theme → Theme tokens: uses theme tokens
src/office/engine/palette.ts