Miya Desktop

ACP-native desktop workspace for AI agents, local runtimes, external ACP endpoints, MCP tools, and remote-control channels.

The app embeds the Miya agent runtime and channel gateway directly into the desktop binary, while still keeping ACP as the protocol boundary for external agents such as OpenCode, Codex, Claude-compatible tools, or any other ACP endpoint.

Highlights

• ACP-first agent client: connect to embedded Miya agents or external stdio ACP agents.
• Multi-agent sessions: view and switch sessions across enabled agents from one session list.
• Streaming conversations: render assistant output, Markdown, tool calls, thoughts, plans, usage, and stop reasons.
• Embedded runtime: miya-agents and miya-channels are compiled into the desktop app for a single-app install experience.
• Configurable providers and profiles: manage providers, agent profiles, MCP servers, and channels from Settings.
• Remote-control channels: run the embedded channel service to bridge chat platforms into ACP agents.
• Native desktop shell: Wails + Go backend with a React frontend.

Product Scope

Miya Desktop is designed as an operator-focused client rather than a generic chat UI. The core workflow is:

1. Configure providers, profiles, MCP servers, and ACP agent endpoints.
2. Enable one or more agents.
3. Create or resume sessions from the left session list.
4. Interact with agents through a streaming timeline that exposes tool activity and reasoning artifacts.
5. Optionally enable Channels so remote chat tools can control the same agent runtime.

Architecture

React UI
  -> Wails API
  -> Go backend
  -> ACP client manager
  -> embedded miya-agents or external ACP endpoint

For the built-in Miya agent, the desktop app uses an in-process ACP transport. This keeps the same ACP client/server contract without launching a separate miya-agent process.

desktop acp.Client
  -> in-process ACP transport
  -> miya-agents acp.Server
  -> miya-agents runtime

Channels are also embedded:

miya-channels app.Run
  -> channel connector
  -> ACP client
  -> embedded or external agent

The related projects can still run independently:

• miya-agents: agent loop, ACP implementation, MCP support, sessions, tools.
• miya-channels: chat platform gateway that bridges channel messages to ACP agents.

Configuration

Miya Desktop reads and writes the shared Miya config file:

~/.miya/config.json

Important top-level sections:

• agents: external stdio ACP endpoints used by the desktop client.
• profiles: Miya agent runtime profiles.
• providers: model provider credentials and base URLs.
• mcpServers: MCP tool server definitions.
• channels: channel gateway configuration.
• channelsEnabled: desktop preference for auto-starting the embedded channel service.

The built-in Miya agent is owned by Miya Desktop and does not need to be declared in agents.

Example external ACP endpoint:

{
  "id": "opencode",
  "name": "OpenCode",
  "enabled": true,
  "type": "stdio",
  "command": "opencode",
  "args": ["acp"]
}

Miya Desktop injects the built-in Miya Agents endpoint at runtime. This keeps the config file focused on external ACP tools.

Development

Prerequisites:

• Go
• Node.js
• Wails CLI

Install frontend dependencies:

cd frontend
npm install

Run the desktop app in development mode:

wails dev

Build a local production app:

wails build -platform darwin/arm64 -clean -trimpath

Run backend tests:

go test ./...

Run frontend build validation:

cd frontend
npm run build

Release

GitHub Actions provides a release workflow:

.github/workflows/release.yml

The workflow checks out:

• miya-desktop
• miya-agents
• miya-channels

It builds Wails apps and uploads prerelease artifacts:

miya-desktop-darwin-universal.zip
miya-desktop-windows-amd64.zip

Manual release trigger:

gh workflow run Release --field version=v0.1.0-test.3

Repository Layout

app.go                         Wails API surface
internal/agent                 ACP client manager and conversation bridge
internal/agentclient           embedded/external ACP client factory
internal/acpadapter            ACP update normalization
internal/channels              embedded channel service controller
internal/config                shared Miya config service
frontend/src/pages/Chat.jsx    main conversation UI
frontend/src/pages/Settings.jsx configuration UI
docs/                          architecture and roadmap notes

Status

Miya Desktop is in preview. The current focus is stabilizing the agent runtime integration, session model, channel service, and configuration experience before expanding platform packaging and deeper permission controls.