# lucasinstra/opencode-status-popup architecture

> Architecture diagram of the GitHub repository lucasinstra/opencode-status-popup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucasinstra/opencode-status-popup
- Repository: https://github.com/lucasinstra/opencode-status-popup

## Overview

This Windows-only OpenCode plugin turns session and permission events into a shared status indicator. Its main workflow is: OpenCode events update per-instance activity, instances publish presence files, and one supervised PowerShell host renders either a floating pill or tray icon. Users can also switch renderers and tray-idle behavior through server commands, the TUI palette, or renderer menus. The graph preserves the documented renderer and interaction capabilities; several host-side implementation details are unsampled, so those links rely on README evidence.

Main entry points: [`src/index.ts`](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/index.ts) (Plugin setup), [`host/popup.ps1`](https://github.com/lucasinstra/opencode-status-popup/blob/main/host/popup.ps1) (PowerShell host), [`src/paths.ts`](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/paths.ts) (Control request files), [`host/tray.ps1`](https://github.com/lucasinstra/opencode-status-popup/blob/main/host/tray.ps1) (Tray icon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Plugin runtime"]
  node_plugin["Plugin setup<br/>[index.ts]"]
  node_config["Configuration<br/>[config.ts]"]
  node_activity["Session activity<br/>[status.ts]"]
  node_supervisor["Host supervisor<br/>[host.ts]"]
  node_debug["Debug logging<br/>[debug.ts]"]
end

subgraph group_state["Shared state"]
  node_presence["Presence writer<br/>[presence.ts]"]
  node_presencefiles[("Presence files<br/>[paths.ts]")]
  node_sharedprefs["Shared preferences<br/>[sharedMode.ts]"]
  node_sharedposition["Shared position<br/>[sharedPosition.ts]"]
  node_paths["State paths<br/>[paths.ts]"]
  node_requestfiles["Control request files<br/>[paths.ts]"]
end

subgraph group_controls["User controls"]
  node_servercommands["Server commands<br/>[index.ts]"]
  node_tuicommands["Palette commands<br/>[tui.ts]"]
end

subgraph group_host["Windows host"]
  node_powershell["PowerShell host<br/>[popup.ps1]"]
  node_window["Floating pill<br/>[window.ps1]"]
  node_tray["Tray icon<br/>[tray.ps1]"]
  node_trayicon["Tray rendering<br/>[TrayIcon.cs]"]
end

node_opencode(("OpenCode"))
node_user(("User"))

node_opencode -->|"loads plugin"| node_plugin
node_plugin -->|"parses options"| node_config
node_plugin -->|"creates tracker"| node_activity
node_plugin -->|"publishes state"| node_presence
node_activity -->|"provides snapshot"| node_presence
node_presence -->|"writes presence"| node_presencefiles
node_plugin -->|"ensures host"| node_supervisor
node_supervisor -->|"spawns host"| node_powershell
node_powershell -->|"reads presence"| node_presencefiles
node_powershell -->|"renders window"| node_window
node_powershell -->|"renders tray"| node_tray
node_tray -.->|"uses renderer"| node_trayicon
node_user -->|"invokes commands"| node_servercommands
node_user -->|"chooses palette"| node_tuicommands
node_user -->|"uses menu"| node_window
node_user -->|"uses menu"| node_tray
node_servercommands -->|"updates choices"| node_sharedprefs
node_tuicommands -->|"writes requests"| node_requestfiles
node_servercommands -->|"polls requests"| node_requestfiles
node_requestfiles -->|"applies requests"| node_sharedprefs
node_plugin -->|"publishes position"| node_sharedposition
node_sharedposition -->|"supplies placement"| node_powershell
node_plugin -->|"resolves state paths"| node_paths
node_plugin -->|"creates logger"| node_debug
node_window -->|"requests mode"| node_requestfiles
node_tray -->|"requests mode"| node_requestfiles

click node_plugin "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/index.ts"
click node_config "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/config.ts"
click node_activity "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/status.ts"
click node_presence "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/presence.ts"
click node_presencefiles "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/paths.ts"
click node_sharedprefs "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/sharedMode.ts"
click node_sharedposition "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/sharedPosition.ts"
click node_paths "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/paths.ts"
click node_supervisor "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/host.ts"
click node_debug "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/debug.ts"
click node_servercommands "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/index.ts"
click node_tuicommands "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/tui.ts"
click node_requestfiles "https://github.com/lucasinstra/opencode-status-popup/blob/main/src/paths.ts"
click node_powershell "https://github.com/lucasinstra/opencode-status-popup/blob/main/host/popup.ps1"
click node_window "https://github.com/lucasinstra/opencode-status-popup/blob/main/host/window.ps1"
click node_tray "https://github.com/lucasinstra/opencode-status-popup/blob/main/host/tray.ps1"
click node_trayicon "https://github.com/lucasinstra/opencode-status-popup/blob/main/host/TrayIcon.cs"

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_plugin,node_config,node_activity,node_supervisor,node_debug,node_user toneBlue
class node_presence,node_presencefiles,node_sharedprefs,node_sharedposition,node_paths,node_requestfiles toneAmber
class node_servercommands,node_tuicommands toneMint
class node_powershell,node_window,node_tray,node_trayicon toneRose
class node_opencode toneIndigo
```

## Components

### Plugin runtime

- [Plugin setup](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/index.ts): `src/index.ts`
- [Configuration](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/config.ts): `src/config.ts`
- [Session activity](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/status.ts): `src/status.ts`
- [Host supervisor](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/host.ts): `src/host.ts`
- [Debug logging](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/debug.ts): `src/debug.ts`

### Shared state

- [Presence writer](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/presence.ts): `src/presence.ts`
- [Presence files](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/paths.ts): `src/paths.ts`
- [Shared preferences](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/sharedMode.ts): `src/sharedMode.ts`
- [Shared position](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/sharedPosition.ts): `src/sharedPosition.ts`
- [State paths](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/paths.ts): `src/paths.ts`
- [Control request files](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/paths.ts): `src/paths.ts`

### User controls

- [Server commands](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/index.ts): `src/index.ts`
- [Palette commands](https://github.com/lucasinstra/opencode-status-popup/blob/main/src/tui.ts): `src/tui.ts`

### Windows host

- [PowerShell host](https://github.com/lucasinstra/opencode-status-popup/blob/main/host/popup.ps1): `host/popup.ps1`
- [Floating pill](https://github.com/lucasinstra/opencode-status-popup/blob/main/host/window.ps1): `host/window.ps1`
- [Tray icon](https://github.com/lucasinstra/opencode-status-popup/blob/main/host/tray.ps1): `host/tray.ps1`
- [Tray rendering](https://github.com/lucasinstra/opencode-status-popup/blob/main/host/TrayIcon.cs): `host/TrayIcon.cs`

### Other components

- **OpenCode**
- **User**

## Connections

- OpenCode → Plugin setup: loads plugin (evidence: `README.md`)
- Plugin setup → Configuration: parses options (evidence: `src/index.ts`)
- Plugin setup → Session activity: creates tracker (evidence: `src/index.ts`)
- Plugin setup → Presence writer: publishes state (evidence: `src/index.ts`)
- Session activity → Presence writer: provides snapshot (evidence: `src/index.ts`)
- Presence writer → Presence files: writes presence (evidence: `src/presence.ts`)
- Plugin setup → Host supervisor: ensures host (evidence: `src/index.ts`)
- Host supervisor → PowerShell host: spawns host (evidence: `README.md`)
- PowerShell host → Presence files: reads presence
- PowerShell host → Floating pill: renders window (evidence: `README.md`)
- PowerShell host → Tray icon: renders tray (evidence: `README.md`)
- Tray icon → Tray rendering: uses renderer
- User → Server commands: invokes commands (evidence: `README.md`)
- User → Palette commands: chooses palette (evidence: `README.md`)
- User → Floating pill: uses menu (evidence: `README.md`)
- User → Tray icon: uses menu (evidence: `README.md`)
- Server commands → Shared preferences: updates choices (evidence: `src/index.ts`)
- Palette commands → Control request files: writes requests (evidence: `src/tui.ts`)
- Server commands → Control request files: polls requests (evidence: `src/index.ts`)
- Control request files → Shared preferences: applies requests (evidence: `src/index.ts`)
- Plugin setup → Shared position: publishes position (evidence: `src/index.ts`)
- Shared position → PowerShell host: supplies placement (evidence: `README.md`)
- Plugin setup → State paths: resolves state paths (evidence: `src/index.ts`)
- Plugin setup → Debug logging: creates logger (evidence: `src/index.ts`)
- Floating pill → Control request files: requests mode (evidence: `README.md`)
- Tray icon → Control request files: requests mode (evidence: `README.md`)
