# OMP Switch

[中文文档](README.md) · [Install and downloads](docs/install.md) · [Architecture](CLAUDE.md) · [OMP schema tracking](docs/omp-schema-tracking.md)

A desktop companion for safely managing [Oh My Pi](https://github.com/can1357/oh-my-pi) (OMP)
model-provider configuration.

It edits **files you own and it does not**: `~/.omp/agent/models.yml` and `config.yml`. Everything
about the architecture follows from that — hash-guarded writes, preserved YAML comments and unknown
fields, a snapshot before every commit, and read-only mode for unknown OMP schema versions.

> **v0.6.0: full Linux support** — desktop GUI (AppImage/deb), a terminal UI, and the credential
> vault (libsecret primary / age fallback). Windows behavior is unchanged. The binaries are
> **not code-signed**, so SmartScreen will warn; verify `SHA256SUMS.txt` and the build-provenance
> attestations. A clean-Windows install/upgrade/uninstall regression now runs nightly.

![OMP Switch provider workspace](docs/images/provider-workspace.png)

![Roles page, dark theme](docs/images/roles-dark.png)

## Three artifacts

| Artifact | Windows | Linux | Contains |
| --- | --- | --- | --- |
| **Desktop app** (GUI, credential vault, gateway, prompts/skills/sessions) | Supported | Supported (v0.6.0) | Everything |
| **Headless CLI** (`omp-switch-cli`) | Supported | Supported | Config read/write, validation, snapshots |
| **TUI** (`omp-switch-tui`, built from source) | Supported | Supported | Interactive terminal config editing (`pnpm build:tui`) |

Credentials are platform-keyed: on Windows, API keys are sealed with Electron `safeStorage` (the
user's DPAPI key) and resolved by the C# secret bridge; on Linux, each key is a **direct libsecret
keyring entry** resolved by `secret-tool` (no bridge binary), with an age keyfile fallback when no
Secret Service is available — see [docs/security.md](docs/security.md).

The headless CLI and the TUI have no Electron dependency (`packages/core` / `packages/shared` are
pure Node), so they run anywhere Node 24 does. The CLI cannot open the credential vault — only the
machine that sealed a key can.

## Install

```powershell
scoop bucket add omp-switch https://github.com/skh2945932142/omp-switch
scoop install omp-switch
```

```bash
# Linux (deb / AppImage from the Releases page)
sudo dpkg -i OMP-Switch-0.6.0-linux.deb
# or chmod +x OMP-Switch-0.6.0-linux.AppImage and run it
```

winget carries the package since 0.3.0 (`winget install skh2945932142.OMPSwitch`, the 0.6.0
update is submitted); the Chocolatey package is prepared with its feed submission still pending —
see [docs/install.md](docs/install.md).

```bash
docker run --rm -v "$HOME/.omp:/home/node/.omp" \
  ghcr.io/skh2945932142/omp-switch-cli:0.6.0 validate --profile default
```

> The image is pushed to GHCR, but GitHub creates container packages as private and visibility is a
> repository setting. If the pull reports `unauthorized`, see
> [docs/install.md](docs/install.md#docker) — a local `docker build` always works.

Every method, including checksum and provenance verification, is in
**[docs/install.md](docs/install.md)**.

## Implemented

**Configuration editing**

- OMP `16.x` / `17.x` / `18.x` writable; unknown future majors read-only.
- Default and named profiles, `models.yml` / `config.yml`, legacy `models.json` migration guard, and
  OMP's own path overrides (`PI_CONFIG_DIR`, `OMP_PROFILE`, `PI_PROFILE`, `PI_CODING_AGENT_DIR`).
- Provider / model / `modelProviderOrder` / `enabledModels` / `disabledProviders` / thinking
  settings.
- YAML AST patching, external-edit protection, atomic writes, snapshots and guarded restore.
- 54 versioned presets; OpenAI, Ollama, llama.cpp, LM Studio, proxy and LiteLLM discovery.

**Model roles**

- A dedicated Roles page: each role shows a one-line gloss, its resolved selector chain
  (`@default → provider/model`), capability chips, and in-place warnings for `@role` cycles,
  unparseable selectors, and `:off`/`:auto` misuse. Custom roles from `config.yml` are listed and
  editable instead of invisible.
- A searchable model picker: provider-grouped results with instant filtering, pinned
  `@default`/`*`/clear values, a segmented thinking-level control (only the six levels OMP accepts
  as a role suffix), full keyboard navigation — shared with gateway upstream rows.
- Quick-assign from any model row: one click assigns a provider/model to a role, preserving that
  role's thinking suffix.

**Other modules**

- Prompts, skills, and session indexing with on-demand raw reads; a usage dashboard (spend,
  requests, tokens, per-day trend, per-model/per-provider breakdowns, cost labelled by provenance).
- Loopback gateway: `/healthz`, `/v1/models`, chat, responses, pre-stream failover, mandatory bearer
  token, `Host` validation and cross-origin refusal.
- Windows DPAPI secret bridge, OMP OAuth status/login entry points, stable JSON CLI.

**Interface**

- A "Quiet Instrument" visual language: untinted zinc neutrals, teal reserved as a signal color for
  selection and focus, ink/paper inversion for primary actions, status as a dot plus quiet text;
  selected rows use a soft fill rather than a 3px rail, and eyebrows are sentence case.
- A manual light / dark / system theme switch (persisted, mirrored by the native title-bar
  buttons), plus a 中文 / English / System language switch (persisted; first paint already
  matches the stored locale, no Chinese flash); plus a Mica window material on Windows 11
  22H2+ (everything else falls back to solid surfaces automatically).
- A custom title bar: the web topbar is the drag region with native overlay window buttons (Snap
  Layouts kept), and Mica reaches the top edge.
- Provider cards: clicking the header only expands/collapses the model list (animated); an edit
  pencil appears on hover. The detail/editor drawer springs in as a floating sheet instead of
  squeezing the workspace.
- Context-scoped saves (roles and settings commit independently) with pending-change dots and
  `Ctrl+S`; switching profiles confirms before discarding unsaved edits.
- **Preview-before-write**: every commit shows a line-level diff of what `models.yml` /
  `config.yml` will receive before anything touches disk; a snapshot timeline browses and restores
  history; external-edit conflicts surface as a dialog with one-click reload.
- **Command palette** (`Ctrl+K`) over sections, profiles, providers, and actions; `Ctrl+1…7`
  section switching; `?` for the shortcut reference.
- Provider cards and the role picker flag `enabledModels` coverage, warning when a picked model
  would be filtered out of OMP's catalog.

## Security boundaries

- Never reads or modifies OMP's `agent.db`, OAuth refresh tokens, or account-rotation state.
- Never writes project-local `.omp` overrides automatically (read-only overlays).
- Never uploads keys, snapshots, diagnostics, or exports anywhere.
- No cloud sync, no automatic account rotation, no downloading unknown binaries.
- API keys never enter OMP configuration; only a command reference does. That rule is enforced in
  `packages/core`, so the CLI path is bound by it too.

See [SECURITY.md](SECURITY.md) and [docs/security.md](docs/security.md).

## Running from source

Requires Windows 10/11, Node.js 24+, pnpm 11+, .NET SDK 10.0, and the Visual Studio "Desktop
development with C++" workload (the secret bridge publishes as Native AOT and links with MSVC).

```powershell
pnpm install --frozen-lockfile
pnpm dev
```

Building only the cross-platform CLI needs neither .NET nor MSVC:

```bash
pnpm install --frozen-lockfile
pnpm build:cli
node packages/cli/dist/main.js --help
```

## Verifying and packaging

```powershell
pnpm typecheck
pnpm test
pnpm build
pnpm package:win        # -> dist/ NSIS installer + portable ZIP
pnpm verify:package-cli # runs the packaged JSON CLI in a temp HOME
pnpm render:packaging   # renders winget / Scoop / Chocolatey manifests from real release hashes
```

Build output is local and never committed.

## Profiles and recovery

- Default profile: `~/.omp/agent/`
- Named profiles: `~/.omp/profiles/<name>/agent/`

A local snapshot is created before every write. If another tool or a manual edit changed a file after
it was loaded, the app stops and asks for a reload instead of overwriting it.

## Developer documentation

- [CLAUDE.md](CLAUDE.md) — architecture, write-path contract, per-module invariants
- [docs/install.md](docs/install.md) — every install method and the platform limits
- [docs/security.md](docs/security.md) — threat model and credential handling
- [docs/releasing.md](docs/releasing.md) — release process
- [CHANGELOG.md](CHANGELOG.md) — version history
- [CONTRIBUTING.md](CONTRIBUTING.md) — contribution workflow

## License

[MIT License](LICENSE)