CC Switch Headless

Headless Linux All-in-One manager for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent

🌐 The Only Official Website: github.com/tiezbro/cc-switch-headless

English | 中文 | Changelog

Disclaimer

Community-maintained headless Linux distribution based on CC Switch. Not an official farion1231/cc-switch release.

This repository is not a second CC Switch. Official CC Switch remains the product. We add a Linux headless runtime so that same core can run on servers without a GUI, and we stay aligned with official updates.

The desktop product's website is ccswitch.io. This project's site is this GitHub repository. Copyright and MIT notices: LICENSE, NOTICE.

Sponsor

This repository is independently maintained. If you would like to sponsor the work to finish CC Switch Headless, please contact me:

• Email: yelingbin@gmail.com
• GitHub: @tiezbro

This is not the official CC Switch sponsor list. Desktop-app sponsors belong on farion1231/cc-switch.

Why CC Switch Headless?

Official CC Switch already unifies the tools:

• One App, Eight Tools — Manage Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes from a single interface
• No More Manual Editing — 50+ provider presets including AWS Bedrock, NVIDIA NIM, and community relays; just pick and switch
• Unified MCP & Skills Management — One panel to manage MCP servers and Skills across Claude, Codex, Gemini, Grok Build, OpenCode, and Hermes with bidirectional sync
• System Tray Quick Switch — Switch providers instantly from the tray menu, no need to open the full app
• Cloud Sync — Sync provider data across devices via Dropbox, OneDrive, iCloud, or WebDAV servers
• Cross-Platform — Native desktop app for Windows, macOS, and Linux, built with Tauri 2
• Built-in Utilities — First-launch login confirmation, signature bypass, plugin extension sync, and more

A lot of multi-agent work now happens on remote VMs. Claude Code, Codex, OpenCode, OpenClaw, Grok Build, and Hermes are CLI products: they already run on Linux servers. Official CC Switch is a Tauri desktop app. On a VM there is no display session, no tray, and no WebKitGTK — the official UI does not start.

That gap is why Headless exists. On one remote Linux host you can:

• configure each agent's providers in one place
• manage Skills and MCP across those agents together
• do it without a graphical session, over SSH or a browser

We do not reimplement CC Switch. We keep adapting the official product.

Current status

This project is just getting started. We are still shaping CC Switch Headless.

If you are interested, please star the repo — you will see the whole product grow from here.

Not a new CC Switch

Official CC Switch stays the product. This repository keeps that core and only adds the Linux runtime a desktop app cannot provide on a server without a GUI.

Operators (SSH / browser)
  → cc-switch-ctl and Web UI     (this project; planned)
      → cc-switch-daemon         (this project; Linux, no Tauri)
          → official Services / DAO / Proxy / live-file writes
              (cc-switch/ at the pin in UPSTREAM.lock)
                  → ~/.cc-switch/cc-switch.db
                  → live CLI configs (Claude Code, Codex, OpenCode, …)
                  → ~/.cc-switch-headless/   (auth, session, audit only)

Layer	Who owns it	What we do
Official CC Switch (cc-switch/)	farion1231/cc-switch	Import the tree. Reuse Schema, migrations, DAO, Service, Proxy, and live config writes. Follow official tags.
Headless runtime	This repository	Linux daemon, local CLI, browser control plane. No Tauri window, WebKitGTK, X11, Wayland, or tray.
Web-only state	This repository	Auth, session, and audit live under ~/.cc-switch-headless/. They are not extra columns on official cc-switch.db.

Each Headless version tracks one official tag/commit (see UPSTREAM.lock). Updates come in with git subtree pull --prefix=cc-switch --squash against official tags. Official git history is not merged into this main, and the official Schema is not forked.

Architecture

Official CC Switch already uses these patterns. We keep them:

• SSOT — providers, MCP, prompts, and skills live in ~/.cc-switch/cc-switch.db
• Dual-layer storage — SQLite for syncable data; JSON for device-level settings
• Dual-way sync — write live CLI files on switch; backfill from live when editing the active provider
• Atomic writes — temp file + rename so configs are not truncated
• Single writer — cc-switch-daemon will be the only process that writes the database and live files (do not run the official desktop app against the same data at the same time)

What changes is how you reach that core, not the core itself:

┌─────────────────────────────────────────────────────────────┐
│  Browser UI / cc-switch-ctl                                 │
│  (Headless transport; planned)                              │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP / local CLI
┌────────────────────────▼────────────────────────────────────┐
│  cc-switch-daemon  (Linux headless runtime)                 │
│  no Tauri · no display server                               │
└────────────────────────┬────────────────────────────────────┘
                         │ same Services → DAO → Database
┌────────────────────────▼────────────────────────────────────┐
│  Official tree in cc-switch/                                │
│  Provider / MCP / Skills / Proxy / Sessions                 │
└─────────────────────────────────────────────────────────────┘

Names

Role	Id
Product	CC Switch Headless
Repository	cc-switch-headless
Daemon	cc-switch-daemon
CLI	cc-switch-ctl
systemd	cc-switch-daemon.service

What we inherit vs what we add

From official CC Switch (Linux CLI apps; Claude Desktop stays on the desktop product): provider presets and switching, unified MCP and Skills, prompts, proxy/failover where those Linux agents support it, sessions, usage, backups. Behavior tracks the pinned official version.

What Headless adds: a systemd service, a daemon as the single writer, cc-switch-ctl for SSH, and a browser UI for the same jobs — Linux only (x86_64 and aarch64).

This project:

• runs on Linux servers without a GUI
• reuses the official database, migrations, services, proxy, and live config writes
• does not add tables or columns to official cc-switch.db
• does not turn every desktop window command into an HTTP API

Upstream pin

Field	Value
Upstream	farion1231/cc-switch
Tag	v3.20.0
Commit	0b5da510168914b251481654a568c3ffacd62cf4
Schema	17
Import	cc-switch/ (git subtree, --squash)

Full field set: UPSTREAM.lock.

To follow a newer official tag:

git fetch upstream tag vX.Y.Z
git subtree pull --prefix=cc-switch --squash upstream vX.Y.Z

Then update UPSTREAM.lock (tag, commit, schema_version).

Repository layout

cc-switch-headless/
├── README.md / README_ZH.md
├── CHANGELOG.md              # this project
├── LICENSE / NOTICE
├── UPSTREAM.lock
├── docs/
└── cc-switch/                # official tree at the pin

Official sources appear only under cc-switch/. This GitHub repo is independent public git; it is not a GitHub Fork of farion1231/cc-switch.

Development

There is no Headless daemon build yet. Upstream checks (run inside cc-switch/):

pnpm --dir cc-switch typecheck
pnpm --dir cc-switch format:check
pnpm --dir cc-switch test:unit
cargo test --manifest-path cc-switch/src-tauri/Cargo.toml

Toolchain pins are in UPSTREAM.lock.

Contributing

Issues and suggestions are welcome. Please discuss first if a change would fork the official Schema, reimplement services, or target Windows, macOS, or a desktop window.

Acknowledgements

CC Switch Headless exists because of official CC Switch.

Thank you to farion1231/cc-switch and Jason Young for the All-in-One manager, the SQLite core, and the MCP/Skills model this project keeps adapting.

If you want the official desktop app or its sponsor list, go to the upstream project. To sponsor this Headless work, see Sponsor.

License

MIT. Original files in this repository are copyright tiezbro (2026). Upstream CC Switch remains copyright Jason Young and is imported under cc-switch/. See LICENSE and NOTICE.