Metadata-Version: 2.5
Name: muse-code-openrouter
Version: 0.2.1
Summary: Use OpenRouter API keys and models directly inside Meta Muse Code
Project-URL: Homepage, https://xhluca.github.io/muse-code-openrouter/
Project-URL: Repository, https://github.com/xhluca/muse-code-openrouter
Project-URL: Issues, https://github.com/xhluca/muse-code-openrouter/issues
Project-URL: Installer, https://xhluca.github.io/muse-code-openrouter/install.sh
Author: xhluca
License-Expression: MIT
License-File: LICENSE
Keywords: coding-agent,muse-code,muse-spark,openrouter
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Muse Code OpenRouter

Use an OpenRouter API key and any `meta/muse*` model directly inside Meta Muse
Code. After setup, the normal `muse` command uses `meta/muse-spark-1.2` through
OpenRouter by default; no Codex configuration is involved.

## Why an adapter is needed

Muse Code 0.2.1 exposes a `--base-url` option but the shipped binary only enables
its `meta` and `echo` providers. Pointing that Meta provider straight at
OpenRouter fails before inference because Muse first requests the proprietary
`/muse-code/models` catalog. Muse also requires a `sequence_number` on each
Responses API stream event, which compatible providers do not always emit.

The local adapter fixes those protocol differences:

- translates OpenRouter's live `meta/muse*` catalog into Muse's model catalog;
- replaces Muse's endpoint with a loopback-only Responses API adapter;
- supplies the OpenRouter credential without putting it in Muse's Meta auth store;
- preserves the requested `meta/muse*` model instead of pinning one model;
- clamps Muse's output budget to each advertised model limit;
- adds missing stream sequence numbers; and
- shortens and restores provider-incompatible function names when necessary.

## Install

```bash
curl -LsSf https://xhluca.github.io/muse-code-openrouter/install.sh | sh
```

The installer installs Meta's official Muse Code launcher if `muse` is missing,
installs this package for the current user, and prompts for the OpenRouter key
without echoing it. Afterwards, use Muse Code normally:

```bash
muse
```

List every currently available Meta Muse model and mark the configured default:

```bash
muse-openrouter models
```

Select any listed model for a run without reconfiguring the adapter:

```bash
muse --model meta/muse-glimmer-30b
muse --model meta/muse-spark-1.1
muse --model meta/muse-spark-1.2
muse --model meta/muse-spark-1.2-contributor
```

The catalog is fetched live, so newly released `meta/muse*` models appear
automatically. OpenRouter account privacy settings and provider availability
still apply. In particular, the Contributor model allows prompts and outputs to
be used to improve Meta's products and may be blocked by restrictive OpenRouter
data policies.

Manual installation is also supported:

```bash
uv tool install muse-code-openrouter
muse-openrouter setup
muse-openrouter doctor --live
```

For automation, supply the key on standard input so it does not appear in shell
history or the process list:

```bash
printf '%s\n' "$OPENROUTER_API_KEY" | muse-openrouter setup --key-stdin
```

## What setup changes

- Stores the key at
  `${XDG_CONFIG_HOME:-~/.config}/muse-code-openrouter/credential`, mode `0600`.
- Preserves Muse's other settings while updating `provider`, `model`, and
  `endpoint_transport` in `~/.config/muse/settings.json`.
- Removes any old static model catalog so Muse reads the adapter's live
  `meta/muse*` catalog.
- Saves the original Muse settings under
  `${XDG_STATE_HOME:-~/.local/state}/muse-code-openrouter/`.
- Starts a loopback-only adapter on `127.0.0.1:8817`, normally as a systemd user
  service on Linux.

The adapter never logs API keys, authorization headers, prompts, request bodies,
or model responses. Muse session logging remains controlled by Muse itself.

## Development

```bash
uv run --with pytest pytest
uv run --with ruff ruff check .
uv build
```

The adapter is dependency-free Python and supports Linux and macOS. The service
installer uses systemd when available and otherwise launches a detached process.
