@pipod/pi-muse-subscription

Meta Muse models in pi through the Muse Code SDK on your Muse Code subscription, with pi's own agent loop, tools and prompt.

Packages

Package details

extension

Install @pipod/pi-muse-subscription from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@pipod/pi-muse-subscription
Package
@pipod/pi-muse-subscription
Version
0.2.2
Published
Nov 14, 2026
Downloads
633/mo · 633/wk
Author
edverma2
License
MIT
Types
extension
Size
92.8 KB
Dependencies
2 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@pipod/pi-muse-subscription

The pi-pod fork of pi-muse-subscription, retaining the upstream MIT license and author attribution. Provider IDs remain muse-sdk/*; do not install both packages together.

pi-pod changes

  • Loads the complete official-client catalog before startup model selection and --list-models. The offline snapshot includes Wonder 1.0, Ember 1.0, Spark 1.3 / 1.2 and both Spark Contributor variants. Listing Contributor models does not change your saved contributor-mode setting or bypass subscription checks.
  • Supports /login muse-sdk through the official Muse SDK device-code flow, including pipod's remote login UI. Pi stores only a non-secret connection marker; official-client credentials remain on the machine running inference.
  • Muse 1.4.18 requires trust before it loads MCP tools. Only an empty, private workspace is trusted; your project rules, hooks and extra MCP servers are not loaded a second time. Pi tools still operate in Pi's real working directory.
  • Complete tool batches wait for the qualified raw-log event even when a typed tool-start event arrives first. Raw batches are enabled only on Muse 1.4.14, 1.4.18 and 1.4.20; other builds use the stable single-call path.
  • Shutdown waits for Muse's session writer lease before a Pi reload or replacement, so resume does not spuriously fork.
  • Explicit subs_active: false in the official client's saved account metadata blocks new turns and tool-result continuations with an actionable inactive-plan error. Missing metadata is not interpreted as proof of entitlement.
  • pipod.clientExtensions: [] declares that the provider runs only in the pod, not again in the launcher's rendering process. This requires pipod's client-entrypoint support; older pipod versions do not honor that declaration.

Connect inside pipod

Install the official muse executable inside the pod (for example in the template init script), then use /login muse-sdk in the attached Pi session and approve its device code in your browser. Select /model muse-sdk/muse-spark-1.3. A laptop login or a copied Pi marker does not authenticate a different pod. Official-client state must be persisted with that pod's home for reconnects. Account-level pipod credentials sharing is not supported for this client-managed login.

This fork does not promise subscription entitlement or billing classification from a local login marker. Use the official client's account/usage surfaces to confirm your plan. No API-key environment fallback is passed to the child.

Use your Muse Code subscription in pi. This pi provider runs Meta's Muse models (Muse Spark, Muse Wonder) through the Muse Code SDK and a local muse serve host, while pi keeps its own agent loop, tools, system prompt, compaction and session tree. Muse Code serves only as the authenticated model transport.

pi install npm:@pipod/pi-muse-subscription
# or: pi install git:github.com/pi-pod/pi-muse-subscription
/model muse-sdk/muse-spark-1.3

Qualified host: Pi 1.5.2, Node 26, and Muse Code 1.4.18 / 1.4.20. Requires Node ≥ 22.19 and Muse Code ≥ 1.4.14 signed in with your subscription (brew install muse-code or curl -fsSL https://dev.meta.ai/install.sh | sh, then muse → /login).

A Muse Code subscription key is accepted only from the Muse Code client. pi's built-in meta provider calls the Model API directly, so with that key it fails with 403 client_attestation_denied. This provider sends every request through Muse Code itself.

How it works

sequenceDiagram
    participant L as pi agent loop
    participant P as provider
    participant M as muse serve<br/>(one per conversation)
    participant B as MCP bridge<br/>(loopback HTTP, in pi)
    Note over M: system prompt = pi's prompt<br/>toolset = pi's tools only
    L->>P: streamSimple
    P->>M: turn/start (MSP)
    M-->>P: text, reasoning, usage, tool calls
    P-->>L: toolCall events (all calls of the response)
    M->>B: MCP tools/call (parked)
    L->>L: pi runs the tools
    L->>P: streamSimple (tool results)
    P->>B: results release the parked calls
    M-->>P: turn continues
  • pi's prompt and tools, not Muse Code's. Each host gets a private Muse Code config directory whose settings set run.system_prompt to pi's prompt and run.toolset to pi's tools, which a loopback MCP server serves. Muse Code's 48k-character system prompt, its 26 built-in tools, skill catalog, observer agents (goal, verify, skill, todo, memory, scope reminders: each one an extra model call per turn) and foreign rules are off. A request carries pi's prompt plus about 2k characters of Muse Code context (workspace root, permission mode, memory index).
  • One live host per conversation. pi's next provider call after a tool round delivers the tool results to the parked MCP calls, matched by the model's call id, and Muse Code continues the same turn. Muse Code runs a response's tool calls one at a time; the provider reads the whole set from the session's raw log as soon as the response is committed, so pi still runs them in parallel.
  • Steering is native. A message you type while tools run goes in with turn/steer before the results are released, so the model sees it at that tool boundary.
  • Divergence resumes or forks Muse Code's own session. Each completed turn is recorded in an anchor registry (pi transcript hash → Muse Code session and turn). After an abort, /tree navigation, a fork or a pi restart, the provider finds the longest recorded prefix and either resumes that session (when the turn is still its last clean one) or forks it at that turn with session/fork. Muse Code replays its own record, so nothing is re-sent as text.
  • Foreign history is carried as text. Turns from other providers, a compacted session or a session from before the extension start a fresh Muse Code session whose first turn carries the earlier conversation in a <conversation_history> block.
  • One-shot requests, such as compaction and branch summaries, run tool-less and unpersisted.
  • pi owns context. Muse Code's own compaction is pushed to 99% of its window, and pi plans against a smaller window, so pi always compacts first. Tool calls never time out on the Muse Code side (tool_timeout_sec is a week); pi's own timeouts apply.

Billing and privacy

  • Subscription only. META_API_KEY and MODEL_API_KEY are removed from Muse Code's environment: Muse Code prefers it over the account login, which would move every request to pay-as-you-go billing.
  • Contributor mode. Muse Code subscriptions default to Contributor mode, where Meta may train on your prompts, code and outputs in exchange for more usage. This provider passes an explicit --contributor-mode: your saved Muse Code setting if you ever saved one, otherwise off. Override with "contributorMode": "on" in muse-sdk.json or PI_MUSE_SDK_CONTRIBUTOR=on|off.
  • Requests identify as Muse Code SDK traffic: the user agent is Muse Code's, followed by pi_muse_subscription/<version>.
  • Usage is reported in tokens; cost shows as 0 because the plan is flat-rate. Check your allowance with muse usage.

System prompt

For muse-sdk models the extension replaces pi's default prompt prefix with one written for Muse models. It lists the selected tools and keeps every tool and prompt guideline that pi and other extensions contribute. pi's context files, skills and working directory are unchanged, and your own SYSTEM.md always wins. Set "promptMode": "pi" in muse-sdk.json, or PI_MUSE_SDK_PROMPT=pi, to keep pi's default prompt.

Configuration

Optional muse-sdk.json in pi's agent directory (~/.pi/agent, or $PI_CODING_AGENT_DIR):

{ "museBin": "/opt/homebrew/bin/muse", "maxSessions": 3, "idleMinutes": 20, "contributorMode": "off" }

A project's .pi/muse-sdk.json can set maxSessions and idleMinutes only: pi reads it before project trust, so a project cannot choose which program runs or opt you into Contributor mode. PI_MUSE_SDK_MUSE_PATH overrides the executable path.

  • PI_MUSE_SDK_DEBUG=/path/log: routing decisions (live / resume / fork / synth / fresh).
  • Thinking levels map one to one onto Muse reasoning efforts (off → none, … max). Levels a model does not offer are disabled.
  • Models: a bundled snapshot (muse-spark-1.3, muse-wonder-1.0, muse-spark-1.2), replaced by Muse Code's live catalog for your plan once a pi session starts.
  • Muse Code sessions are stored by Muse Code (~/.local/share/muse), so they also appear in muse resume.

Experimental surface

The Muse Code SDK is a developer preview. Two things this provider relies on are not covered by its stability promise:

  • the raw session log (rawLog capability, experimental), used to hand pi all tool calls of a response at once. Without it the provider still works, but pi receives a response's calls one at a time;
  • the settings keys for the system prompt, toolset, observers, skills and context slimming, which were found in Muse Code 1.4.14 rather than in its documentation. @muse-code/sdk is pinned to the same version; check npm run test:host after a Muse Code upgrade.

Tests

  • npm test: offline unit tests.
  • npm run test:host: the provider against the installed muse serve, offline. A local fake serves Muse Code's model endpoint and records every request. It covers prompt and tool replacement, one request per turn, parallel tool calls, steering, restart resume, fork, foreign history, tool-less requests, abort recovery and the live catalog. PI_MUSE_SDK_SLOW=1 adds a tool call parked for 6.5 minutes.
  • npm run test:e2e: pi's own agent loop (pi -p) over the extension and muse serve, offline: the model reads a file through pi's read tool.
  • npm run test:live: against Muse Code and Meta on your login (spends a few prompts).