# mindedtech/busy-octopus architecture

> Architecture diagram of the GitHub repository mindedtech/busy-octopus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mindedtech/busy-octopus
- Repository: https://github.com/mindedtech/busy-octopus

## Overview

Busy Octopus is a VS Code extension and companion CLI/library for routing agent, command, or direct notifications to the matching workspace. The main path resolves workspace identity, publishes a validated request to a filesystem queue, then the extension consumes it and dispatches to enabled editor or Windows channels. Agent setup and command wrapping are separate CLI capabilities. Queue and dispatcher wiring is supported by sampled source; CLI command details and several extension subsystems are represented from the tree and README, so uncertain internal calls are omitted.

Main entry points: [`src/workspace/resolution.ts`](https://github.com/mindedtech/busy-octopus/blob/main/src/workspace/resolution.ts) (Workspace resolution), [`src/extension/delivery/dispatcher.ts`](https://github.com/mindedtech/busy-octopus/blob/main/src/extension/delivery/dispatcher.ts) (Delivery dispatcher), [`src/cli/run.ts`](https://github.com/mindedtech/busy-octopus/blob/main/src/cli/run.ts) (Command wrapper), [`src/library/notify.ts`](https://github.com/mindedtech/busy-octopus/blob/main/src/library/notify.ts) (Notification API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & Agents"]
  node_cli["CLI commands<br/>[cli.ts]"]
  node_entry["CLI entry<br/>[main.ts]"]
  node_run["Command wrapper<br/>[run.ts]"]
  node_agent["Agent commands<br/>[agent.ts]"]
  node_agentsetup["Hook &amp; skill setup<br/>[setup.ts]"]
  node_provider["Provider adapters<br/>[provider.ts]"]
  node_library["Notification API<br/>[notify.ts]"]
  node_notifycli["Direct notify<br/>[notify.ts]"]
end

subgraph group_workspace["Workspace &amp; Protocol"]
  node_workspace["Workspace resolution<br/>[resolution.ts]"]
  node_identity["Workspace identity<br/>[identity.ts]"]
  node_protocol["Request protocol<br/>[notification.ts]"]
end

subgraph group_queue["Queue Transport"]
  node_queueapi["Queue coordinator<br/>[queue.ts]"]
  node_queueloc["Queue location<br/>[queue.ts]"]
  node_queuefs["Native queue FS<br/>[file-system.ts]"]
end

subgraph group_extension["VS Code Delivery"]
  node_extension["Extension activation<br/>[extension.ts]"]
  node_consumer["Workspace consumer"]
  node_extconsumer["Queue consumer<br/>[consumer.ts]"]
  node_vscodefs["VS Code queue FS<br/>[file-system.ts]"]
  node_dispatcher["Delivery dispatcher<br/>[dispatcher.ts]"]
  node_editor["Editor notifications<br/>[editor.ts]"]
  node_windowsnotify["Windows notifications<br/>[notification.ts]"]
  node_taskbar["Taskbar flash<br/>[taskbar.ts]"]
  node_bridge["Windows bridge<br/>[bridge.ts]"]
end

node_user(("User or agent"))
node_vscode(("VS Code host"))
node_powershell["Windows PowerShell"]

node_user -->|"runs CLI"| node_entry
node_entry -->|"starts program"| node_cli
node_cli -->|"dispatches"| node_run
node_cli -->|"dispatches"| node_agent
node_agent -->|"configures"| node_agentsetup
node_agentsetup -->|"selects adapter"| node_provider
node_agentsetup -->|"resolves directory"| node_workspace
node_user -->|"calls API"| node_library
node_user -->|"runs notify"| node_notifycli
node_notifycli -->|"selects workspace"| node_workspace
node_library -->|"resolves directory"| node_workspace
node_workspace -->|"identifies workspace"| node_identity
node_workspace -->|"creates context"| node_protocol
node_run -->|"resolves workspace"| node_workspace
node_run -->|"creates request"| node_protocol
node_notifycli -->|"creates request"| node_protocol
node_library -->|"creates request"| node_protocol
node_run -->|"locates queue"| node_queueloc
node_notifycli -->|"locates queue"| node_queueloc
node_library -->|"locates queue"| node_queueloc
node_queueloc -->|"publishes request"| node_queueapi
node_queueapi -->|"writes request"| node_queuefs
node_vscode -->|"activates"| node_extension
node_extension -->|"starts consumption"| node_consumer
node_consumer -->|"creates consumers"| node_extconsumer
node_extconsumer -->|"claims request"| node_queueapi
node_queueapi -->|"reads queue"| node_vscodefs
node_extension -->|"delivers test request"| node_dispatcher
node_extconsumer -->|"dispatches request"| node_dispatcher
node_dispatcher -->|"sends notification"| node_editor
node_dispatcher -.->|"sends notification"| node_windowsnotify
node_dispatcher -.->|"flashes taskbar"| node_taskbar
node_windowsnotify -->|"invokes native operation"| node_bridge
node_taskbar -->|"controls flash"| node_bridge
node_bridge -->|"runs scripts"| node_powershell

click node_cli "https://github.com/mindedtech/busy-octopus/blob/main/src/cli/cli.ts"
click node_entry "https://github.com/mindedtech/busy-octopus/blob/main/src/cli/main.ts"
click node_run "https://github.com/mindedtech/busy-octopus/blob/main/src/cli/run.ts"
click node_agent "https://github.com/mindedtech/busy-octopus/blob/main/src/cli/agent.ts"
click node_agentsetup "https://github.com/mindedtech/busy-octopus/blob/main/src/integration/agent/setup.ts"
click node_provider "https://github.com/mindedtech/busy-octopus/blob/main/src/integration/agent/provider.ts"
click node_library "https://github.com/mindedtech/busy-octopus/blob/main/src/library/notify.ts"
click node_notifycli "https://github.com/mindedtech/busy-octopus/blob/main/src/cli/notify.ts"
click node_workspace "https://github.com/mindedtech/busy-octopus/blob/main/src/workspace/resolution.ts"
click node_identity "https://github.com/mindedtech/busy-octopus/blob/main/src/workspace/identity.ts"
click node_protocol "https://github.com/mindedtech/busy-octopus/blob/main/src/protocol/notification.ts"
click node_queueapi "https://github.com/mindedtech/busy-octopus/blob/main/src/queue/queue.ts"
click node_queueloc "https://github.com/mindedtech/busy-octopus/blob/main/src/workspace/queue.ts"
click node_queuefs "https://github.com/mindedtech/busy-octopus/blob/main/src/queue/file-system.ts"
click node_extension "https://github.com/mindedtech/busy-octopus/blob/main/src/extension/extension.ts"
click node_consumer "https://github.com/mindedtech/busy-octopus/blob/main/src/extension/workspace-consumer.ts"
click node_extconsumer "https://github.com/mindedtech/busy-octopus/blob/main/src/extension/queue/consumer.ts"
click node_vscodefs "https://github.com/mindedtech/busy-octopus/blob/main/src/extension/queue/file-system.ts"
click node_dispatcher "https://github.com/mindedtech/busy-octopus/blob/main/src/extension/delivery/dispatcher.ts"
click node_editor "https://github.com/mindedtech/busy-octopus/blob/main/src/extension/delivery/adapter/editor.ts"
click node_windowsnotify "https://github.com/mindedtech/busy-octopus/blob/main/src/extension/delivery/adapter/windows/notification.ts"
click node_taskbar "https://github.com/mindedtech/busy-octopus/blob/main/src/extension/delivery/adapter/windows/taskbar.ts"
click node_bridge "https://github.com/mindedtech/busy-octopus/blob/main/src/extension/windows/bridge.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_entry,node_run,node_agent,node_agentsetup,node_provider,node_library,node_notifycli,node_user toneBlue
class node_workspace,node_identity,node_protocol toneAmber
class node_queueapi,node_queueloc,node_queuefs toneMint
class node_extension,node_consumer,node_extconsumer,node_vscodefs,node_dispatcher,node_editor,node_windowsnotify,node_taskbar,node_bridge toneRose
class node_vscode,node_powershell toneIndigo
```

## Components

### CLI & Agents

- [CLI commands](https://github.com/mindedtech/busy-octopus/blob/main/src/cli/cli.ts): `src/cli/cli.ts`
- [CLI entry](https://github.com/mindedtech/busy-octopus/blob/main/src/cli/main.ts): `src/cli/main.ts`
- [Command wrapper](https://github.com/mindedtech/busy-octopus/blob/main/src/cli/run.ts): `src/cli/run.ts`
- [Agent commands](https://github.com/mindedtech/busy-octopus/blob/main/src/cli/agent.ts): `src/cli/agent.ts`
- [Hook & skill setup](https://github.com/mindedtech/busy-octopus/blob/main/src/integration/agent/setup.ts): `src/integration/agent/setup.ts`
- [Provider adapters](https://github.com/mindedtech/busy-octopus/blob/main/src/integration/agent/provider.ts): `src/integration/agent/provider.ts`
- [Notification API](https://github.com/mindedtech/busy-octopus/blob/main/src/library/notify.ts): `src/library/notify.ts`
- [Direct notify](https://github.com/mindedtech/busy-octopus/blob/main/src/cli/notify.ts): `src/cli/notify.ts`

### Workspace & Protocol

- [Workspace resolution](https://github.com/mindedtech/busy-octopus/blob/main/src/workspace/resolution.ts): `src/workspace/resolution.ts`
- [Workspace identity](https://github.com/mindedtech/busy-octopus/blob/main/src/workspace/identity.ts): `src/workspace/identity.ts`
- [Request protocol](https://github.com/mindedtech/busy-octopus/blob/main/src/protocol/notification.ts): `src/protocol/notification.ts`

### Queue Transport

- [Queue coordinator](https://github.com/mindedtech/busy-octopus/blob/main/src/queue/queue.ts): `src/queue/queue.ts`
- [Queue location](https://github.com/mindedtech/busy-octopus/blob/main/src/workspace/queue.ts): `src/workspace/queue.ts`
- [Native queue FS](https://github.com/mindedtech/busy-octopus/blob/main/src/queue/file-system.ts): `src/queue/file-system.ts`

### VS Code Delivery

- [Extension activation](https://github.com/mindedtech/busy-octopus/blob/main/src/extension/extension.ts): `src/extension/extension.ts`
- [Workspace consumer](https://github.com/mindedtech/busy-octopus/blob/main/src/extension/workspace-consumer.ts): `src/extension/workspace-consumer.ts`
- [Queue consumer](https://github.com/mindedtech/busy-octopus/blob/main/src/extension/queue/consumer.ts): `src/extension/queue/consumer.ts`
- [VS Code queue FS](https://github.com/mindedtech/busy-octopus/blob/main/src/extension/queue/file-system.ts): `src/extension/queue/file-system.ts`
- [Delivery dispatcher](https://github.com/mindedtech/busy-octopus/blob/main/src/extension/delivery/dispatcher.ts): `src/extension/delivery/dispatcher.ts`
- [Editor notifications](https://github.com/mindedtech/busy-octopus/blob/main/src/extension/delivery/adapter/editor.ts): `src/extension/delivery/adapter/editor.ts`
- [Windows notifications](https://github.com/mindedtech/busy-octopus/blob/main/src/extension/delivery/adapter/windows/notification.ts): `src/extension/delivery/adapter/windows/notification.ts`
- [Taskbar flash](https://github.com/mindedtech/busy-octopus/blob/main/src/extension/delivery/adapter/windows/taskbar.ts): `src/extension/delivery/adapter/windows/taskbar.ts`
- [Windows bridge](https://github.com/mindedtech/busy-octopus/blob/main/src/extension/windows/bridge.ts): `src/extension/windows/bridge.ts`

### Other components

- **User or agent**
- **VS Code host**
- **Windows PowerShell**

## Connections

- User or agent → CLI entry: runs CLI
- CLI entry → CLI commands: starts program
- CLI commands → Command wrapper: dispatches
- CLI commands → Agent commands: dispatches
- Agent commands → Hook & skill setup: configures
- Hook & skill setup → Provider adapters: selects adapter
- Hook & skill setup → Workspace resolution: resolves directory
- User or agent → Notification API: calls API
- User or agent → Direct notify: runs notify
- Direct notify → Workspace resolution: selects workspace
- Notification API → Workspace resolution: resolves directory
- Workspace resolution → Workspace identity: identifies workspace
- Workspace resolution → Request protocol: creates context
- Command wrapper → Workspace resolution: resolves workspace
- Command wrapper → Request protocol: creates request
- Direct notify → Request protocol: creates request
- Notification API → Request protocol: creates request
- Command wrapper → Queue location: locates queue
- Direct notify → Queue location: locates queue
- Notification API → Queue location: locates queue
- Queue location → Queue coordinator: publishes request
- Queue coordinator → Native queue FS: writes request
- VS Code host → Extension activation: activates
- Extension activation → Workspace consumer: starts consumption
- Workspace consumer → Queue consumer: creates consumers
- Queue consumer → Queue coordinator: claims request
- Queue coordinator → VS Code queue FS: reads queue
- Extension activation → Delivery dispatcher: delivers test request
- Queue consumer → Delivery dispatcher: dispatches request
- Delivery dispatcher → Editor notifications: sends notification
- Delivery dispatcher → Windows notifications: sends notification
- Delivery dispatcher → Taskbar flash: flashes taskbar
- Windows notifications → Windows bridge: invokes native operation
- Taskbar flash → Windows bridge: controls flash
- Windows bridge → Windows PowerShell: runs scripts