Table of Contents

• 1. What is OpenSunstar
  • GUI + CLI(TUI) dual-mode
  • Target users
  • Core use cases (8 scenarios)
  • Six pain points we solve
  • Feature overview
• 2. Installation
• 3. Quick Start
• 4. FAQ
• Appendix
  • Documentation
  • Development
  • Contributing
  • Acknowledgements
  • License

1. What is OpenSunstar

OpenSunstar is a cross-platform native desktop app (Tauri 2 + React) — a local-first, all-in-one platform for AI coding workflow engineering configuration.

本地优先，一站式统一管理你的 AI 编程工作流工程化配置平台
跨多项目组合矩阵以AI驱动的项目驾驶舱，一站式帮你基于项目的AI资产配置&工作流编排和跨工具跨设备Agent扩展配置同步

Move from “edit config files by hand” to “see project health, orchestrate workflows, fill asset gaps, and keep shipping.”

GUI + CLI(TUI) dual-mode

OpenSunstar ships two independent entry points that share the same data under ~/.OpenSunstar/:

Run CLI without starting the GUI — os bootstraps OpenSunstar.db on first use (os config bootstrap or automatic). Governance, provider switch, and the TUI work standalone.

Shared state, not isolated silos — changes in GUI or CLI both read/write the same SQLite DB and live CLI configs.

Dual-mode, independently startable; data is unified. For proxy takeover (Claude Code / Codex / Gemini), keep the desktop app running until headless os proxy ships.

Product narrative (aligned with the current sidebar)

OpenSunstar is no longer documented as a single provider switcher. Its source-of-truth navigation is the sidebar: a local-first engineering platform where projects, AI assets, workflow orchestration, Agent extensions, model access, sync, and collaboration share one cockpit.

Target users

Core personas (5 types)

Who it is not for

• Teams with no AI CLI workflow (no Claude Code / Codex / Gemini need)
• Users on one official subscription only, never switching providers
• PMs needing Jira / Linear-style task boards — Workspace is an AI governance dashboard, not issue tracking
• Teams wanting a hosted SaaS config hub — OpenSunstar is local-first with optional cloud sync

Core use cases (8 scenarios)

1. Project Cockpit governance — Today Alerts, Project Board, project readiness, and asset gaps
2. Methodology & workflow orchestration — framework detection, preset orchestration, custom Recipe, design contract
3. One-click API access — Quick Start for Claude Code / Desktop / Codex / Gemini with 22+ preset providers plus custom aggregators/relays
4. Cross-tool Agent sync — 9 agent modules with bidirectional sync
5. Context management — multi-CLI session browse, search, and restore
6. AI usage & cost — Token dashboard, budget alerts, investment reports
7. MCP & Skills discovery — Smithery, skills.sh leaderboard, ClawHub, ModelScope
8. Backup & cross-device sync — WebDAV / S3 / Gist, Deep Link import

Six pain points we solve

Feature overview

Supported CLI tools

Screenshots

Project Cockpit	AI Asset Configuration

v1.2.0 — Project Wiki baselines, project asset workflow improvements, usage sidecar storage, and Apache-2.0 licensing; database schema v43.

2. Installation

Desktop GUI (recommended for visual management)

Get the latest build from GitHub Releases.

Requirements: Windows 10+ · macOS 12+ · Ubuntu 22.04+ / Debian 11+ / Fedora 34+

OpenSunstar CLI (os) — standalone binary (no GUI required)

Use os without the GUI for governance checks, provider switching, and a full-screen TUI dashboard. No need to launch the desktop app first — the CLI creates ~/.OpenSunstar/OpenSunstar.db on first run.

Install options (pick one):

opensunstar-os is a thin Node wrapper that downloads the native binary from GitHub Releases on install — not a JS reimplementation. See docs/cli-distribution-p1.md.

# npm global install (good for agents / CI)
npm install -g opensunstar-os

# or manual: unzip Release asset and add to PATH

# First run (creates ~/.OpenSunstar/OpenSunstar.db)
os config bootstrap --yes

# Full-screen TUI dashboard (interactive terminal — run with no subcommand)
os

# Common commands
os doctor --json
os drift check --json
os provider list --app claude
os provider switch --app claude --id <provider-id> --yes

See AGENTS.md for Agent integration.

Build from source

See Development in the appendix.

3. Quick Start

First launch

1. OpenSunstar can auto-import existing CLI configs as your default provider on first run.
2. Complete the onboarding wizard if prompted.

Connect a CLI in three steps

1. Open sidebar → Quick Start (快速接入)
2. Pick a target app: Claude Code, Claude Desktop, Codex, or Gemini
3. Choose a curated supplier → enter API key (or follow official OAuth guidance) → Verify & Apply

For official providers (Anthropic / OpenAI / Google), Quick Start links you to Settings → Provider management for browser login.

Proxy note: When proxy takeover is enabled for Claude Code, Codex, Gemini, or Claude Desktop, keep the desktop app running so the local proxy on :15721 stays up. Pure governance and os provider switch do not require the GUI.

Switch providers

• Use the main UI or system tray to switch active provider
• Restart the terminal for most CLIs after switching (Claude Code supports hot-switch)

Set up your workspace

1. Sidebar → Workspace → Add project and point to local Git repos
2. Open Project Cockpit → Today Alerts for attention items and readiness gaps
3. Use Project Board for commit activity and AI portfolio reports
4. Open a project's AI Assets to manage MCP / Skills / Prompts at repo level

Explore agent tooling

4. FAQ

Seven tools: Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, OpenClaw, and Hermes. Quick Start currently guides the first four; all seven are manageable from provider and agent panels.

Usually yes. Claude Code is the exception and supports hot-switching without a restart.

For several CLIs, OpenSunstar writes a local proxy endpoint into the tool config. Closing the app stops the proxy and the CLI may show connection errors until OpenSunstar is running again.

Add or select an Official preset provider, switch to it, then run the CLI's Log out / Log in flow in your terminal.

No. Workspace is a multi-repo AI governance dashboard — Git health, agent readiness, project-scoped assets, and AI insights — not a drag-and-drop issue board.

Data is fetched from skills.sh and cached locally (~6 hours). The UI shows last sync time; use refresh to force an update.

Appendix

Documentation

Development

Stack: React 18 · TypeScript · Vite · Tauri 2 · Rust · SQLite · TanStack Query

Prerequisites: Node.js 22.13+ · pnpm 11.5.2 · Rust 1.95.0 · platform Tauri dependencies

pnpm dev:doctor       # verify local toolchain
pnpm install
pnpm tauri dev        # dev mode (desktop)
pnpm dev:renderer     # frontend only
pnpm typecheck        # TypeScript
pnpm test:unit        # unit tests
pnpm tauri build      # production build

Contributing

Issues and pull requests are welcome. Before submitting:

pnpm typecheck && pnpm format:check && pnpm test:unit

See CONTRIBUTING.md. Partner and sponsor info: SUPPORT.md.

Acknowledgements

OpenSunstar builds upon the open-source cc-switch project. OpenSunstar will continue to evolve independently, anchored to its strategic positioning, value proposition, and product narrative.

License

Apache License 2.0

The desktop app, os CLI, and local capabilities in this repository form the public client. The hosted commercial control plane—accounts, subscriptions and billing, multi-tenant team services, and cloud operations—is separate proprietary software and is not covered by this repository's license. See Licensing and product boundary.