elizaos--eliza/plugins/plugin-app-control/README.md

# @elizaos/plugin-app-control

An elizaOS plugin that lets an Eliza agent launch, close, list, scaffold, and verify Eliza apps; manage UI views contributed by plugins; and change the unified app background.

## What it does

Loading this plugin gives an Eliza agent three new actions:

**APP** — Unified app lifecycle control. The agent can:
- Launch a registered app by name (`"launch shopify"`)
- Relaunch (stop then start) a running app, optionally running verification after (`"relaunch shopify and verify"`)
- List installed and currently-running apps (`"what apps are open?"`)
- Load apps from a local directory into the registry (`"load apps from /my/dev/apps"`)
- Scaffold a new Eliza app through a multi-turn flow that asks new/edit/cancel, scaffolds from the min-app template, and dispatches a coding agent with AppVerificationService validation (`"build me a note-taking app"`)

**VIEWS** — Full view management. The agent can navigate to any UI view contributed by any loaded plugin; report the currently-open view; search views by name; open the view manager; broadcast events to mounted views; interact with a view (click, get state, focus, etc.); pin a view as a desktop tab; open a view in a separate window; and create, edit, or delete view plugins through a coding-agent backed flow.

**BACKGROUND** — Unified background control. The agent can set a named color or hex color, use an uploaded image, generate a background image from a prompt, undo the previous background, redo an undone change, or reset to default. It broadcasts a `background:apply` view event that the always-mounted app background applies to the shared `BackgroundConfig` store.

## Capabilities added to the agent

| Action | Contexts gated | Role gate |
|---|---|---|
| `APP` | `automation`, `settings`, `code` | Owner |
| `VIEWS` (read modes) | `general`, `automation`, `settings`, `code` | User |
| `VIEWS` (create/edit/delete) | `general`, `automation`, `settings`, `code` | Owner |
| `BACKGROUND` | `general`, `settings` | User |

The `available_apps` provider injects installed + running app data into the agent's planning context when operating in the `settings` or `automation` context, so the agent can pick a target without an extra round-trip.

## Installation

Add `@elizaos/plugin-app-control` to your agent's plugin list. The plugin is not default-enabled.

```ts
import appControlPlugin from "@elizaos/plugin-app-control";

const runtime = new AgentRuntime({
  // ...
  plugins: [appControlPlugin],
});
```

## Required environment / config

None are required for basic operation. The plugin auto-discovers the Eliza dashboard port via `resolveServerOnlyPort`.

| Variable | Purpose |
|---|---|
| `ELIZA_REPO_ROOT` / `ELIZA_WORKSPACE_DIR` | Repo root used when scaffolding new apps or view plugins. Defaults to `cwd()`. |
| `ELIZA_STATE_DIR` | State directory for the app registry, audit logs, and granted-permissions store. Defaults to `~/.eliza`. |
| `ELIZA_PROTECTED_APPS` | Comma-separated app slugs the agent may not delete. |
| `ELIZA_BROWSER_VERIFY_OPTIONAL` | Set to `1` to make browser checks in AppVerificationService non-fatal. |
| `ELIZA_CHROME_PATH` / `PUPPETEER_EXECUTABLE_PATH` | Chrome binary path for browser-based app verification (optional peer dep `puppeteer-core`). |
| `ELIZA_BUILD_VARIANT=store` / `ELIZA_PLATFORM=ios\|android` | Disables dynamic plugin creation on restricted distribution platforms. |

## Services registered

| Service | Purpose |
|---|---|
| `AppRegistryService` | Persists `load_from_directory` registrations so they survive restarts. |
| `AppVerificationService` | Typecheck / lint / test / build / launch / browser pipeline for newly created apps and plugins. |
| `AppWorkerHostService` | Runs apps that declare `isolation: "worker"` in a dedicated `node:worker_threads` Worker with typed RPC. |
| `VerificationRoomBridgeService` | Posts verification results back into the user's chat room once the background coding agent finishes. |

## Views registered

The plugin contributes a **View Manager** GUI view at `/views` — a browser for all views contributed by loaded plugins.

## For agent developers

See [CLAUDE.md](CLAUDE.md) for file layout, how to add new sub-modes, service wiring, and plugin-specific gotchas.