Desktop tray viewer for every SAIPEN project on your machine
Autodiscovers .saipen/ projects across local drives — live phase, task, blocker, git status, tickets, and sub-agents.
One vintage dark-golden Win95-themed dashboard.
Every SAIPEN project, sub-agent, ticket, and git status — all in one view.
|
|
| 🐍 Run from source | 📜 Launch scripts | 📦 Install (future) | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
git clone https://github.com/vacterro/saipenview.git
cd saipenview
python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
.venv\Scripts\python -m saipenview |
|
pip install saipenview
saipenviewComing soon ✨ |
| Action | How |
|---|---|
| Show / Hide | Ctrl+Alt+X or Alt+F15 (both configurable) |
| Snap corner | Ctrl+Q — cycles Top-Left → Top-Right → Bottom-Left → Bottom-Right |
| Kill switch | Ctrl+Shift+Alt+Q — force-quit the process |
| Zoom in / out | Ctrl+MouseWheel or Ctrl + + / - |
| Zoom reset | Ctrl+0 |
| Toggle toolbar | Alt+D — collapse/expand the toolbar panel |
| Search projects | Type in search box; tick D for deep ticket search |
| Filter | Dropdown: All / Live / Done / Stuck, or click a phase pill |
| Sort | Smart / Recent / Oldest / A–Z / Z–A |
| Rescan | Click Rescan or wait for background timer (default 300s) |
| Browse folder | Click Browse to add a folder to the scan set |
| Settings | ⚙ button opens the settings modal |
| Help wiki | ? button opens the built-in mini-wiki |
| Right-click project | Copy root path, filter by phase, open folder |
| Double-click section | Opens the connected file (STATE.md, BOARD.md, LOG.md) |
| Drag window | Drag the title bar (or anywhere in frameless mode) |
| Modal | What it does |
|---|---|
| Settings | Zoom, hotkeys, scan tuning, autostart, always-on-top, font, flash toggle, file viewer default, custom commands, locale, scan roots |
| File Viewer | Read & edit STATE.md, BOARD.md, LOG.md — Source (raw) or Reader (rendered) mode |
| Help | Comprehensive mini-wiki covering every feature, shortcut, and concept |
| Confirm | Vintage-styled DOM dialog (replaces native confirm()) |
SAIPENVIEW is a companion for projects using the SAIPEN Protocol — a state-machine framework that guides AI agents through project work in defined phases:
INIT → PLAN → SCOUT → BUILD → REVIEW → VERIFY → SHIP → DONE
↓
HUNT / CLEAN
Each SAIPEN project stores its state in three canonical files:
| File | Purpose |
|---|---|
.saipen/STATE.md |
Machine-readable frontmatter — phase, task, next action, blocker |
.saipen/BOARD.md |
Ticket board — DOING / TODO / DONE / BLOCKED sections |
.saipen/LOG.md |
Chronological event log — every command and its outcome |
SubSaipen agents (saiwiki, saihunt, saitranslate) live in .saipen/extensions/subs/ and communicate via kitchen/OUTBOX.md — the protocol's built-in cross-agent message bus. SAIPENVIEW discovers all of them and renders a unified dashboard.
💡 The name "SAIPENVIEW" says it all — it provides a view into every SAIPEN project on your machine.
Config is portable — stored next to the app, not %APPDATA%:
saipenview/_data/config.json
Key defaults:
{
"hotkeys": ["ctrl+alt+x", "alt+f15"],
"snap_hotkey": ["ctrl+q", "alt+f14"],
"zoom_level": 1.0,
"font_family": "Verdana_m1",
"scan_roots": null,
"rescan_interval": 300,
"scan_depth": 6,
"scan_delay_ms": 10,
"auto_scan": true,
"show_on_launch": true,
"always_on_top": true,
"flash_changes": true,
"locale": "en"
}Set scan_roots: null to autodetect all local drives.
Set to a list of paths (e.g. ["V:\\", "D:\\projects"]) to limit scanning.
All settings are also configurable through the Settings modal in the app.
saipenview/
├── app.py Entry wiring — tray, hotkey, window, api
├── api.py JS-facing pywebview bridge (30+ methods)
├── scanner.py Drive walk + background rescan loop
├── parser.py STATE.md / BOARD.md / LOG.md parsing
├── config.py Settings load/save (atomic writes)
├── tray.py pystray system-tray icon + menu
├── hotkey.py Global hotkey registration (keyboard lib)
├── autostart.py Windows Registry autostart management
├── zone_picker.py Ctrl+Q corner-snap overlay (tkinter)
├── ui/
│ ├── window.py pywebview window — show/hide/toggle/snap
│ └── static/
│ ├── index.html
│ ├── style.css Vintage dark-golden Win95 theme
│ └── app.js Frontend logic (~2600 lines)
├── assets/
│ └── tray_icon.png
├── screenshots/ README screenshots
└── _data/ Runtime config + cache (gitignored)
- Single process — no background IPC, no separate server; one Python process hosts both the WebView2 window and the scan loop in a
ThreadPoolExecutor - Atomic writes — every file write uses temp-file +
os.replace; a crash can never truncate config or cache - Stale-read safe — the 5s UI poll calls
refresh_known()(re-reads only.saipen/files, no directory walk). Edits to STATE.md appear within seconds without triggering a full drive scan - No CSS transitions — all visual effects (flash, heat, hover) are JavaScript-driven
hexBlendrecomputations, strictly following the vintage theme's zero-animation constraint - Vintage theme — dark brown surfaces, golden text/accents, 3D beveled borders, zero anti-aliasing, Verdana_m1 font
# Clone & enter
git clone https://github.com/vacterro/saipenview.git
cd saipenview
# Create venv & install
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
# Run
python -m saipenviewFor detailed setup, coding conventions, and PR workflow, see CONTRIBUTING.md.
- Windows 10 / 11 — WebView2 runtime (pre-installed on Win11, auto-installs on Win10)
- Python 3.10+
- Dependencies:
pystray,keyboard,pywebview,Pillow
MIT — see LICENSE.
