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

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 with workspaces spanning packages/**, plugins/**, services/**, examples/**, docs/**, and apps/**.

Install all workspace dependencies:

pnpm i

Launch the default Stage Web development server:

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.

Plugin Architecture and the Host Runtime

The plugin system centers on the PluginHost class defined in 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. The constructor accepts a runtime configuration:

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. 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. 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 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:

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

Define capabilities using the SDK:

// 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:

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:

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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}