10 KiB
Star Office UI
🌐 Language: 中文 | English | 日本語
A pixel office dashboard for multi-agent collaboration — visualize your AI assistants' (OpenClaw / "lobster") work status in real time, so you can see at a glance who's doing what, what they did yesterday, and whether they're online.
This is a co-created project by Ring Hyacinth and Simon Lee.
✨ 30-Second Quick Start
# 1) Clone the repo
git clone https://github.com/ringhyacinth/Star-Office-UI.git
cd Star-Office-UI
# 2) Install dependencies
python3 -m pip install -r backend/requirements.txt
# 3) Initialize state file (first run)
cp state.sample.json state.json
# 4) Start the backend
cd backend
python3 app.py
Open http://127.0.0.1:19000 and try switching states:
python3 set_state.py writing "Organizing documents"
python3 set_state.py error "Found an issue, debugging"
python3 set_state.py idle "Standing by"
📋 Features
- Status Visualization — 6 states (
idle/writing/researching/executing/syncing/error) mapped to different office areas with animated sprites and speech bubbles - Yesterday Memo — Automatically reads the latest daily log from
memory/*.md, sanitizes it, and displays it as a "Yesterday Memo" card - Multi-Agent Collaboration — Invite other agents to join your office via join keys and see everyone's status in real time
- Trilingual UI — Switch between Chinese, English, and Japanese with one click; all UI text, bubbles, and loading messages update instantly
- Custom Art Assets — Manage characters, scenes, and decorations through the sidebar; dynamic frame sync prevents flickering
- AI-Powered Room Design — Connect your own Gemini API to generate new office backgrounds (recommended:
nanobanana-pro/nanobanana-2); core features work fine without an API - Mobile-Friendly — Open on your phone for a quick status check on the go
- Security Hardening — Sidebar password protection, weak-password blocking in production, hardened session cookies
- Flexible Public Access — Use Cloudflare Tunnel for instant public access, or bring your own domain / reverse proxy
- Desktop Pet Mode — Optional Tauri desktop wrapper that turns the office into a transparent desktop widget (see below)
🚀 Getting Started
1) Install dependencies
cd Star-Office-UI
python3 -m pip install -r backend/requirements.txt
2) Initialize state file
cp state.sample.json state.json
3) Start the backend
cd backend
python3 app.py
Open http://127.0.0.1:19000
✅ For local development you can start with the defaults; in production, copy
.env.exampleto.envand set strong random values forFLASK_SECRET_KEYandASSET_DRAWER_PASSto avoid weak passwords and session leaks.
4) Switch states
python3 set_state.py writing "Organizing documents"
python3 set_state.py syncing "Syncing progress"
python3 set_state.py error "Found an issue, debugging"
python3 set_state.py idle "Standing by"
5) Public access (optional)
cloudflared tunnel --url http://127.0.0.1:19000
Share the https://xxx.trycloudflare.com link with anyone.
6) Verify your installation (optional)
While the backend is running, you can run a lightweight smoke test to confirm that the core endpoints are healthy:
python3 scripts/smoke_test.py --base-url http://127.0.0.1:19000
If all checks report OK, your Star Office UI service is wired up correctly for basic status flows.
🦞 For OpenClaw Users
If you're using OpenClaw, these three steps deeply integrate your lobster with the pixel office.
4.1 Install the Skill
Copy SKILL.md from the repo into your OpenClaw workspace:
cp SKILL.md ~/.openclaw/workspace/SKILL.md
Your lobster will read it automatically and follow the deployment guide — starting the backend, setting up a public link, and prompting you for passwords and API keys.
4.2 Automatic Status Sync
Add the following rule to your SOUL.md (or agent config) so your lobster updates its status automatically:
## Star Office Status Sync Rules
- When starting a task: run `python3 set_state.py <state> "<description>"` before beginning work
- When finishing a task: run `python3 set_state.py idle "Standing by"` before replying
6 states → 3 office areas:
| State | Office Area | When to use |
|---|---|---|
idle |
🛋 Breakroom (sofa) | Standing by / task complete |
writing |
💻 Workspace (desk) | Writing code or docs |
researching |
💻 Workspace | Searching / researching |
executing |
💻 Workspace | Running commands / tasks |
syncing |
💻 Workspace | Syncing data / pushing |
error |
🐛 Bug Corner | Error / debugging |
4.3 Invite Other Lobsters to Your Office
Step 1: Prepare join keys
When you start the backend for the first time, if there is no join-keys.json in the project root, the service will automatically create one based on join-keys.sample.json (which contains an example key such as ocj_example_team_01). You can then edit the generated join-keys.json to add, modify, or remove keys; by default each key supports up to 3 concurrent users.
Step 2: Have the guest run the push script
The guest only needs to download office-agent-push.py and fill in 3 variables:
JOIN_KEY = "ocj_starteam02" # The key you assign
AGENT_NAME = "Alice's Lobster" # Display name
OFFICE_URL = "https://office.hyacinth.im" # Your office URL
python3 office-agent-push.py
The script auto-joins and pushes status every 15 seconds. The guest's lobster will appear on the dashboard, moving to the appropriate area based on its state.
Step 3 (optional): Guest installs a Skill
Guests can also use frontend/join-office-skill.md as a Skill — their lobster will handle setup and pushing automatically.
See
frontend/join-office-skill.mdfor full guest onboarding instructions.
📡 API Reference
| Endpoint | Description |
|---|---|
GET /health |
Health check |
GET /status |
Get main agent status |
POST /set_state |
Set main agent status |
GET /agents |
List all agents |
POST /join-agent |
Guest joins the office |
POST /agent-push |
Guest pushes status |
POST /leave-agent |
Guest leaves |
GET /yesterday-memo |
Get yesterday's memo |
GET /config/gemini |
Get Gemini API config |
POST /config/gemini |
Set Gemini API config |
GET /assets/generate-rpg-background/poll |
Poll image generation progress |
🖥 Desktop Pet Mode (Optional)
The desktop-pet/ directory contains a Tauri-based desktop wrapper that turns the pixel office into a transparent desktop widget.
cd desktop-pet
npm install
npm run dev
- Auto-launches the Python backend on startup
- Window points to
http://127.0.0.1:19000/?desktop=1by default - Customizable via environment variables for project path and Python path
⚠️ This is an optional, experimental feature, primarily developed and tested on macOS. See
desktop-pet/README.mdfor details.
🎨 Art Assets & License
Asset Attribution
Guest character animations use free assets by LimeZu:
Please keep attribution when redistributing or demoing, and follow the original license terms.
License
- Code / Logic: MIT (see
LICENSE) - Art Assets: Non-commercial use only (learning / demo / sharing)
For commercial use, replace all art assets with your own original artwork.
👥 Authors
This project is co-created and maintained by Ring Hyacinth and Simon Lee.
- Ring Hyacinth — @ring_hyacinth
- Simon Lee — @simonxxoo
📝 Changelog
| Date | Summary | Details |
|---|---|---|
| 2026-03-06 | 🔌 Default port updated — backend default port changed from 18791 to 19000 to avoid conflicts with OpenClaw Browser Control; synced scripts, desktop shells, and docs defaults | docs/CHANGELOG_2026-03.md |
| 2026-03-01 | 🎉 v2 Rebuild — Trilingual support, asset management system, AI room design, full art asset overhaul | docs/FEATURES_NEW_2026-03-01.md |
| 2026-03-03 | 📋 Open-source release checklist completed | docs/OPEN_SOURCE_RELEASE_CHECKLIST.md |
| 2026-03-04 | 🔒 P0/P1 Security hardening — weak password blocking, backend refactor, stale-state auto-idle, skeleton loading | docs/UPDATE_REPORT_2026-03-04_P0_P1.md |
| 2026-03-05 | 📱 Stability fixes — CDN cache fix, async image generation, mobile sidebar UX, join key expiration & concurrency | docs/UPDATE_REPORT_2026-03-05.md |
📁 Project Structure
Star-Office-UI/
├── backend/ # Flask backend
│ ├── app.py
│ ├── requirements.txt
│ └── run.sh
├── frontend/ # Frontend pages & assets
│ ├── index.html
│ ├── join.html
│ ├── invite.html
│ └── layout.js
├── desktop-pet/ # Tauri desktop wrapper (optional)
├── docs/ # Documentation & screenshots
│ └── screenshots/
├── office-agent-push.py # Guest push script
├── set_state.py # Status switch script
├── state.sample.json # State file template
├── join-keys.sample.json # Join key template (runtime generates join-keys.json)
├── SKILL.md # OpenClaw Skill
└── LICENSE # MIT License