MusePi — a desktop-first AI coding agent
musepi CLI · Electron desktop GUI · Cordis plugins · daemon service
English | 中文
MusePi combines a coding agent, an Electron workbench, a terminal UI, and remote clients. The desktop app includes an editable file workspace, review tools, a managed browser, a desktop pet, and a capability center for first-party and third-party Cordis plugins. MusePi is independently versioned; reference projects are absorption sources only, never version-alignment targets.
Download version-matched desktop installers and Android packages from the releases page. The MusePi website provides bilingual download guides.
- Desktop: macOS
.dmg, Windows per-usersetup.exe, Linux.AppImage/.deb. - Android: install
app-debug.apkand pair with a host on the local network. - HarmonyOS: the NEXT WebView shell in
apps/harmonybuilds with DevEco Studio; no prebuilt package is published yet. - Terminal: install
musepiwith a script or from source.
macOS, Linux, and WSL:
curl -fsSL https://raw.githubusercontent.com/MuseLinn/MusePi/main/scripts/install.sh | shWindows PowerShell:
irm https://raw.githubusercontent.com/MuseLinn/MusePi/main/scripts/install.ps1 | iexFrom source:
git clone https://github.com/MuseLinn/MusePi.git
cd MusePi
bun run setup
bun run musepiThe sh installer accepts --ref <tag|commit|branch> to select a release or checkout and --source to build instead of downloading the prebuilt binary. The PowerShell installer runs through irm | iex, which passes no arguments: set $env:PI_REF to select a version and $env:PI_SOURCE=1 to build from source before running it.
Prebuilt binaries carry their own runtime; only a from-source install needs Bun 1.4.4 or newer.
- Agent workspace: session history and branching, provider-qualified model selection, slash commands, shell commands, file and session references, approvals, context compaction, and task tracking.
- Editable files: tabs, a non-modal file tree, Monaco-based editing, Markdown editing, document and media viewers, selection references, Git changes, issues, and pull requests.
- Customizable shell: theme, accent, density, liquid-glass surfaces, command palette, configurable shortcuts, right-side surfaces, terminal tabs, and a managed in-app browser.
- Desktop companion: animated pet, status bubbles, tray controls, and cross-window activity updates.
- Capability center: manage skills, plugins, and marketplace packages. Official modules and external packages use the Cordis lifecycle and shared component availability rather than separate package switches.
- Remote access: collaborate through encrypted links, connect remote daemon instances, and use mobile clients to manage sessions.
- Multiple model providers and routing controls; LSP and DAP integration; parallel subagents; session memory; ACP; and local or remote collaboration.
- File, search, shell, code-intelligence, browser, desktop, GitHub, image, speech, memory, and skill tools. Optional tools remain controlled by settings and extension scope.
- Presets combine extension selection, prompt sections, and settings. Session presets lock after the first turn.
Detailed behavior belongs to the living documents under docs/, not to a feature inventory in this README.
flowchart LR
subgraph CLIENTS["Clients"]
DESKTOP["desktop-app<br/>Electron workbench and satellite windows"]
WEB["client-core<br/>shared React rendering and collab web UI"]
MOBILE["mobile / harmony<br/>Android and HarmonyOS shells"]
end
subgraph HOST["coding-agent"]
RPC["daemon services<br/>JSON-RPC and event streams"]
CORDIS["Cordis runtime<br/>first-party and external plugins"]
SESSION["AgentSession<br/>journal and materialized view"]
end
subgraph ENGINE["Agent engine"]
CORE["agent · ai · catalog · wire · sdk"]
TOOLS["tools · TUI · LSP/DAP · collab"]
NATIVE["natives and Rust crates"]
end
DESKTOP <-- "JSON-RPC / WebSocket" --> RPC
WEB <-- "collab link / WebSocket" --> RPC
MOBILE --> WEB
RPC --> CORDIS --> SESSION --> CORE
CORE --> TOOLS --> NATIVE
| Area | Responsibility |
|---|---|
apps/desktop |
Electron shell, desktop renderer, official GUI plugins, installer and updater |
packages/client-core |
Shared React components, transcript, widgets, i18n, and collab web UI |
packages/coding-agent |
CLI, daemon (L2 host services over one RPC dispatcher), sessions, tools, bundled Cordis plugins, and extension runtime |
apps/mobile, apps/harmony |
Android and HarmonyOS shells |
packages/collab-proto, packages/wire, packages/sdk |
Transport, persisted contracts, and client SDK |
packages/agent, packages/ai, packages/catalog |
Agent loop, provider client, and model catalog |
packages/tui |
Terminal UI |
packages/utils, packages/natives, crates/ |
Shared utilities and native implementations |
tools/ |
Benchmark and harness workspaces (metaharness, TypeScript edit benchmark) |
| Other packages | Hashline edits, compaction, memory, tool selection, and statistics |
Contracts and extension boundaries: docs/capability-seams.md, docs/extensions-dev.md, docs/gui-design.md, and docs/gui-implementation.md.
Use Bun 1.4.4 or newer within the project compatibility policy. Package scripts are the command source of truth.
bun run setup # install dependencies, build natives, link the CLI
bun run build # build workspaces that define a build script
bun run check # TypeScript/tooling and Rust checks
bun run test # repository test runner
bun run lint # Biome and Rust lintUseful entry points:
bun run musepi
bun --cwd=packages/coding-agent src/cli.ts serve --port 8300
bun run --cwd=apps/desktop desktopDo not edit packages/catalog/src/models.json directly; update its generator and regenerate. Tests and smoke runs must use isolated configuration and daemon directories. See AGENTS.md and .agents/rules/ for engineering and verification rules.
gui-release.yml builds desktop artifacts and the Android package for version tags. Desktop releases include OTA manifests. macOS distribution requires the signing and notarization process in docs/macos-signing-notarization.md.
The Windows installer collects language and install options in its WebView2 wizard, checks for a running MusePi client, and then shows the real NSIS extraction progress and completion page. It does not hide a background installation behind simulated progress.
Run the release workflow only for an explicit release request. Version and changelog rules live in .agents/rules/release.md.
docs/: product and implementation documentation, with bilingual pairs where required.packages/coding-agent/CHANGELOG.musepi.md: release notes.
