# How to Use moeru-ai/airi: Complete Setup, Development, and Plugin Guide

> Learn how to use moeru-ai/airi by following our complete setup guide. Install dependencies, run the browser or desktop client, and unlock full plugin capabilities.

- Repository: [Moeru AI/airi](https://github.com/moeru-ai/airi)
- Tags: how-to-guide
- Published: 2026-03-08

---

**To use moeru-ai/airi, clone the monorepo, install dependencies with `pnpm i`, and run `pnpm dev` for the browser client or `pnpm dev:tamagotchi` for the Electron desktop version with full plugin support.**

The moeru-ai/airi project provides a comprehensive framework for building AI-driven virtual characters across web, desktop, and mobile platforms. This monorepo bundles three application frontends with a shared UI layer and a runtime-agnostic plugin SDK. Understanding how to use moeru-ai/airi requires familiarity with its pnpm workspace structure, development commands, and the plugin host architecture.

## Repository Architecture Overview

AIRI organizes code into three architectural layers that separate platform-specific applications from shared logic and extensibility systems.

The **Applications** layer delivers the user-facing clients. **Stage Web** (`apps/stage-web`) runs in browsers, **Stage Tamagotchi** (`apps/stage-tamagotchi`) provides the Electron desktop experience, and **Stage Pocket** (`apps/stage-pocket`) builds the Capacitor-based mobile application.

The **Shared UI & Logic** layer supplies reusable infrastructure through `packages/stage-ui`, `packages/stage-ui-three`, `packages/stage-shared`, and `packages/ui`. These packages expose Vue components, composables, and Pinia stores that all three applications consume for consistent theming and behavior.

The **Plugin Runtime** layer manages extensibility via `packages/plugin-sdk`. This directory contains the runtime-agnostic SDK, the `PluginHost` implementation, and the `FileSystemLoader` that dynamically loads plugin modules.

## Development Setup and Commands

AIRI operates as a pnpm workspace defined in the root [`package.json`](https://github.com/moeru-ai/airi/blob/main/package.json) with workspaces spanning `packages/**`, `plugins/**`, `services/**`, `examples/**`, `docs/**`, and `apps/**`.

Install all workspace dependencies:

```bash
pnpm i

```

Launch the default Stage Web development server:

```bash
pnpm dev

```

Execute platform-specific clients using these commands:

- `pnpm dev:tamagotchi` – Starts the Electron desktop client
- `pnpm dev:pocket:ios` – Builds and runs the Capacitor iOS application  
- `pnpm dev:docs` – Serves the documentation site

The default `pnpm dev` command provides the fastest way to interact with AIRI, launching Stage Web with hot-module reload configured in [`apps/stage-web/vite.config.ts`](https://github.com/moeru-ai/airi/blob/main/apps/stage-web/vite.config.ts).

## Plugin Architecture and the Host Runtime

The plugin system centers on the **PluginHost** class defined in [`packages/plugin-sdk/src/plugin-host/core.ts`](https://github.com/moeru-ai/airi/blob/main/packages/plugin-sdk/src/plugin-host/core.ts). This host manages the complete plugin lifecycle from loading through initialization to execution.

In Stage Tamagotchi, the host instantiates within `setupPluginHost()` located at [`apps/stage-tamagotchi/src/main/services/airi/plugins/index.ts`](https://github.com/moeru-ai/airi/blob/main/apps/stage-tamagotchi/src/main/services/airi/plugins/index.ts). The constructor accepts a runtime configuration:

```ts
const host = new PluginHost({ runtime: 'electron' })

```

The host maintains active sessions in a `Map<string, PluginHostSession>` and exposes the `listSessions()` method for runtime inspection. Capabilities register through **Eventa** IPC channels, allowing bidirectional communication between the plugin runtime and the Vue-based UI layer.

UI components interact with the host through the `usePluginHostInspectorStore` composable in [`packages/stage-ui/src/stores/devtools/plugin-host-debug.ts`](https://github.com/moeru-ai/airi/blob/main/packages/stage-ui/src/stores/devtools/plugin-host-debug.ts). This store provides a developer tools panel displaying loaded plugins, lifecycle phases, and available capabilities.

## Desktop Client IPC Implementation

Stage Tamagotchi implements the plugin host bootstrap in [`apps/stage-tamagotchi/src/main/services/airi/plugins/index.ts`](https://github.com/moeru-ai/airi/blob/main/apps/stage-tamagotchi/src/main/services/airi/plugins/index.ts). The setup function registers Eventa invoke handlers including `electronPluginList` and `electronPluginLoad`, which the UI accesses via `invokePluginProtocolListProviders` and related helpers.

The host loads plugin manifests using the `FileSystemLoader`, validates them against the `pluginConfigSchema` (manifest v1), and manages the `load → init → start → stop` lifecycle transitions. Snapshot generation capabilities allow the UI to render real-time plugin state for debugging purposes.

## Creating Custom Plugins for AIRI

Plugins are Node/Electron modules containing a [`manifest.json`](https://github.com/moeru-ai/airi/blob/main/manifest.json) following the v1 schema. The SDK provides type-safe contracts through `manifestV1Schema`, `PluginHost`, and `CapabilityDescriptor` interfaces.

Create a plugin in the `plugins/` directory with this structure:

```json
// manifest.json
{
  "name": "example-plugin",
  "version": "0.1.0",
  "entrypoint": "dist/index.js"
}

```

Define capabilities using the SDK:

```ts
// src/index.ts
import { defineCapability } from '@proj-airi/plugin-sdk/plugin-host'

export const myCapability = defineCapability('example:hello', {
  async handler(payload) {
    return `Hello, ${payload.name}!`
  }
})

```

Invoke capabilities from the UI layer:

```ts
await invokePluginProtocol('example:hello', { name: 'World' })

```

The host automatically registers capabilities when starting the plugin, making them available across the IPC boundary without manual channel management.

## Nix-Based Installation and Execution

For developers using Nix, the repository includes a flake configuration that builds and launches Stage Tamagotchi directly:

```bash
nix run github:moeru-ai/airi

```

This command handles dependency resolution, compilation, and execution in a single step, providing a reproducible environment for the desktop client as documented in the README section "Stage Tamagotchi (Desktop Version)".

## Summary

- **moeru-ai/airi** operates as a pnpm monorepo with workspace definitions spanning apps, packages, and plugins.
- Run `pnpm dev` for the browser client or `pnpm dev:tamagotchi` for the Electron desktop version.
- The **PluginHost** class in [`packages/plugin-sdk/src/plugin-host/core.ts`](https://github.com/moeru-ai/airi/blob/main/packages/plugin-sdk/src/plugin-host/core.ts) manages plugin lifecycles and capability registration via Eventa IPC.
- Plugins follow the manifest v1 schema and expose capabilities through type-safe SDK contracts using `defineCapability()`.
- Desktop client bootstrap occurs in [`apps/stage-tamagotchi/src/main/services/airi/plugins/index.ts`](https://github.com/moeru-ai/airi/blob/main/apps/stage-tamagotchi/src/main/services/airi/plugins/index.ts) with handlers for `electronPluginList` and `electronPluginLoad`.
- Nix users can launch the application via `nix run github:moeru-ai/airi` for a fully reproducible build.

## Frequently Asked Questions

### What is the fastest way to get started with moeru-ai/airi?

Clone the repository, run `pnpm i` to install dependencies, then execute `pnpm dev` to launch Stage Web in your browser. This provides immediate access to the AI character interface without configuring Electron build tools or mobile SDKs.

### How does the plugin system work in AIRI?

The **PluginHost** class loads plugins as Node modules, manages their lifecycle phases (load, init, start, stop), and exposes capabilities through Eventa IPC channels. Plugins define capabilities using `defineCapability()` from `@proj-airi/plugin-sdk`, which the UI invokes via `invokePluginProtocol()` for seamless cross-process communication.

### Can I develop plugins without modifying the core repository?

Yes. Place custom plugins in the `plugins/` directory of the monorepo, ensuring they export a valid [`manifest.json`](https://github.com/moeru-ai/airi/blob/main/manifest.json) and entrypoint. The host dynamically loads these at runtime using the `FileSystemLoader`, allowing extension without rebuilding the core applications or modifying `packages/plugin-sdk` source code.

### Is mobile development supported in moeru-ai/airi?

Yes. The `apps/stage-pocket` directory contains a Capacitor-based mobile client. Run `pnpm dev:pocket:ios` to build and launch the iOS version, leveraging the shared UI components from `packages/stage-ui` for consistent behavior across platforms.