# jackiezheng/xueren-workbuddy-live-progress architecture

> Architecture diagram of the GitHub repository jackiezheng/xueren-workbuddy-live-progress, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jackiezheng/xueren-workbuddy-live-progress
- Repository: https://github.com/jackiezheng/xueren-workbuddy-live-progress

## Overview

This repository is a WorkBuddy task-progress skill: hooks turn prompts and tool activity into task cards, optional reporting paths update their progress, and a local panel displays current and finished work. The main path is prompt/session activity → shared job registry → browser panel, with separate handling for background tasks, explicit script reporting, and bridged external progress. The graph also includes documented hook installation and self-update capabilities. Some links rely on README statements or SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`scripts/progress.py`](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/progress.py) (Job registry), [`scripts/live_panel.py`](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/live_panel.py) (HTTP panel and UI), [`scripts/check_update.py`](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/check_update.py) (Skill updater), [`scripts/hook_session.py`](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_session.py) (Session hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hooks["WorkBuddy hooks"]
  node_installer["Hook installer<br/>[install_hooks.py]"]
  node_prompt_hook["Prompt hook<br/>[hook_prompt.py]"]
  node_session_hook["Session hook<br/>[hook_session.py]"]
  node_tool_hook["Tool step hook<br/>[hook_auto_step.py]"]
  node_background_hook["Background hook<br/>[hook_bg.py]"]
  node_stop_hook["Stop hook<br/>[hook_stop.py]"]
end

subgraph group_tracking["Progress tracking"]
  node_registry["Job registry<br/>[progress.py]"]
  node_job_store[("jobs.json")]
  node_bridge["Progress bridge<br/>[progress_bridge.py]"]
end

subgraph group_panel["Live panel"]
  node_panel["HTTP panel and UI<br/>[live_panel.py]"]
end

subgraph group_operations["Panel operations"]
  node_panel_control["Panel controller<br/>[panel_ctl.py]"]
end

subgraph group_updates["Skill updates"]
  node_updater["Skill updater<br/>[check_update.py]"]
  node_backups["Update backups"]
end

node_user(("WorkBuddy user"))
node_workbuddy(("WorkBuddy runtime"))
node_browser(("Browser viewer"))
node_state_files["External state files"]
node_release_sources(("Release sources"))

node_user -->|"submits prompt"| node_workbuddy
node_installer -->|"configures hooks"| node_workbuddy
node_workbuddy -->|"dispatches prompt"| node_prompt_hook
node_workbuddy -->|"dispatches session"| node_session_hook
node_workbuddy -->|"dispatches tools"| node_tool_hook
node_workbuddy -->|"dispatches background"| node_background_hook
node_workbuddy -->|"dispatches stop"| node_stop_hook
node_prompt_hook -->|"registers session"| node_registry
node_session_hook -->|"prunes and recovers"| node_registry
node_session_hook -->|"reuses panel startup"| node_background_hook
node_tool_hook -->|"records tool steps"| node_registry
node_background_hook -->|"tracks background jobs"| node_registry
node_stop_hook -->|"finishes session jobs"| node_registry
node_bridge -->|"reads progress"| node_state_files
node_bridge -->|"reports progress"| node_registry
node_registry -->|"reads and writes"| node_job_store
node_panel -->|"reads jobs"| node_registry
node_browser -->|"polls APIs"| node_panel
node_panel -->|"serves dashboard"| node_browser
node_panel_control -->|"starts and controls"| node_panel
node_updater -->|"checks and downloads"| node_release_sources
node_updater -->|"backs up package"| node_backups
node_updater -->|"coordinates upgrade"| node_panel_control

click node_installer "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/install_hooks.py"
click node_prompt_hook "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_prompt.py"
click node_session_hook "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_session.py"
click node_tool_hook "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_auto_step.py"
click node_background_hook "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_bg.py"
click node_stop_hook "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_stop.py"
click node_registry "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/progress.py"
click node_bridge "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/progress_bridge.py"
click node_panel "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/live_panel.py"
click node_panel_control "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/panel_ctl.py"
click node_updater "https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/check_update.py"
click node_backups "https://github.com/jackiezheng/xueren-workbuddy-live-progress/tree/main/cache/backups"

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_installer,node_prompt_hook,node_session_hook,node_tool_hook,node_background_hook,node_stop_hook,node_user,node_browser toneBlue
class node_registry,node_job_store,node_bridge toneAmber
class node_panel toneMint
class node_panel_control toneRose
class node_updater,node_backups,node_workbuddy,node_state_files,node_release_sources toneIndigo
```

## Components

### WorkBuddy hooks

- [Hook installer](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/install_hooks.py): `scripts/install_hooks.py`
- [Prompt hook](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_prompt.py): `scripts/hook_prompt.py`
- [Session hook](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_session.py): `scripts/hook_session.py`
- [Tool step hook](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_auto_step.py): `scripts/hook_auto_step.py`
- [Background hook](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_bg.py): `scripts/hook_bg.py`
- [Stop hook](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/hook_stop.py): `scripts/hook_stop.py`

### Progress tracking

- [Job registry](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/progress.py): `scripts/progress.py`
- **jobs.json**
- [Progress bridge](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/progress_bridge.py): `scripts/progress_bridge.py`

### Live panel

- [HTTP panel and UI](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/live_panel.py): `scripts/live_panel.py`

### Panel operations

- [Panel controller](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/panel_ctl.py): `scripts/panel_ctl.py`

### Skill updates

- [Skill updater](https://github.com/jackiezheng/xueren-workbuddy-live-progress/blob/main/scripts/check_update.py): `scripts/check_update.py`
- [Update backups](https://github.com/jackiezheng/xueren-workbuddy-live-progress/tree/main/cache/backups): `cache/backups`

### Other components

- **WorkBuddy user**
- **WorkBuddy runtime**
- **Browser viewer**
- **External state files**
- **Release sources**

## Connections

- WorkBuddy user → WorkBuddy runtime: submits prompt (evidence: `README.md`)
- Hook installer → WorkBuddy runtime: configures hooks (evidence: `README.md`)
- WorkBuddy runtime → Prompt hook: dispatches prompt (evidence: `README.md`)
- WorkBuddy runtime → Session hook: dispatches session (evidence: `README.md`)
- WorkBuddy runtime → Tool step hook: dispatches tools (evidence: `README.md`)
- WorkBuddy runtime → Background hook: dispatches background (evidence: `README.md`)
- WorkBuddy runtime → Stop hook: dispatches stop (evidence: `scripts/hook_stop.py`)
- Prompt hook → Job registry: registers session (evidence: `scripts/hook_prompt.py`)
- Session hook → Job registry: prunes and recovers (evidence: `scripts/hook_session.py`)
- Session hook → Background hook: reuses panel startup (evidence: `scripts/hook_session.py`)
- Tool step hook → Job registry: records tool steps (evidence: `scripts/hook_auto_step.py`)
- Background hook → Job registry: tracks background jobs (evidence: `scripts/hook_bg.py`)
- Stop hook → Job registry: finishes session jobs (evidence: `scripts/hook_stop.py`)
- Progress bridge → External state files: reads progress (evidence: `scripts/progress_bridge.py`)
- Progress bridge → Job registry: reports progress (evidence: `scripts/progress_bridge.py`)
- Job registry → jobs.json: reads and writes (evidence: `README.md`)
- HTTP panel and UI → Job registry: reads jobs (evidence: `scripts/live_panel.py`)
- Browser viewer → HTTP panel and UI: polls APIs (evidence: `README.md`)
- HTTP panel and UI → Browser viewer: serves dashboard (evidence: `README.md`)
- Panel controller → HTTP panel and UI: starts and controls (evidence: `README.md`)
- Skill updater → Release sources: checks and downloads (evidence: `README.md`)
- Skill updater → Update backups: backs up package (evidence: `README.md`)
- Skill updater → Panel controller: coordinates upgrade (evidence: `scripts/check_update.py`)
