# Ailoha

> Ailoha gives AI coding agents eyes and hands inside running mobile and desktop apps. It is a small debug-only agent you embed in your app, paired with a host-side CLI that exposes inspection, UI actions, screenshots, logs, network capture, profiling, and storage to any AI tool over MCP or HTTP.

This file follows the [llms.txt](https://llmstxt.org/) convention. Point your AI agent at `https://ailoha.dev/llms.txt` to get a one-shot setup briefing for a project.

## How to set up Ailoha in this project

1. **Detect the framework.** Look at the project files to determine which of these the user's app is built with: .NET MAUI, native Android, Flutter, React Native (bare), Expo, WinUI 3, or WPF. `ailoha init` installs bundled skills for MAUI, native Android, Flutter, React Native, Expo, WinUI, and WPF. If you cannot determine the framework, ask the user.

2. **Install the host CLI** on the developer machine if it is not already installed:

   ```bash
   curl -fsSL https://ailoha.dev/install.sh | bash
   # Windows PowerShell:
   #   iex "& { $(irm https://ailoha.dev/install.ps1) }"
   # See docs/install.md for channels (release / staging / dev) and custom paths.
   ```

   Verify with `ailoha --version`.

3. **Initialize Ailoha skills for the workspace** so future agent runs have authoritative, framework-specific instructions on disk:

   ```bash
   cd <project-root>
   ailoha init
   ```

   This installs Markdown skill files under `.claude/skills/` (default), `.github/skills/`, `.agent/skills/`, or `.agents/skills/` depending on `--target`. Pass `--platforms maui,android,flutter,react-native,expo,winui,wpf` to limit which platforms are installed; otherwise the CLI auto-detects.

4. **Add the agent package** to the user's app project. Use the framework-specific guide:

   - .NET MAUI: <https://ailoha.dev/docs/maui.html>
   - Native Android: <https://ailoha.dev/docs/android.html>
   - Flutter: <https://ailoha.dev/docs/flutter.html>
   - React Native (bare): <https://ailoha.dev/docs/react-native.html>
   - Expo: <https://ailoha.dev/docs/expo.html>
   - WinUI 3: <https://ailoha.dev/docs/winui.html>
   - WPF: <https://ailoha.dev/docs/wpf.html>

   Each guide is a single page with the package install command, the debug-only registration snippet, the configuration table, and a verification step. Read the appropriate page in full before editing files.

5. **Wire the agent up in debug-only code paths**. Never let agent code ship to release builds.

   - .NET MAUI / WinUI / WPF: wrap registration in `#if DEBUG`.
   - Android: use debug source sets, `debugImplementation`, or `if (BuildConfig.DEBUG) { ... }`.
   - Flutter: wrap in `if (kDebugMode) { ... }`.
   - React Native / Expo: wrap in `if (__DEV__) { ... }`.

6. **Use stable element identifiers** so the agent can reliably target UI elements:

   - .NET MAUI / WinUI: `AutomationId="..."` on `VisualElement`s.
   - WPF: `AutomationProperties.AutomationId="..."` on controls.
   - Native Android Views: resource IDs or `view.setAilohaAutomationId("...")`.
   - Jetpack Compose: `Modifier.testTag("...")`.
   - Flutter: `key: const ValueKey('...')` on widgets.
   - React Native / Expo: `testID="..."` on components.

7. **Verify the agent is running.** Launch the app in debug mode, then from the project root run:

   ```bash
   ailoha agent status
   ailoha ui tree
   ```

   The first command should return agent metadata. The second should print the live visual tree.

## Defaults and conventions

- **Default direct agent port:** 9233. Discovery goes through the broker on port 19323; do not hardcode alternate ports.
- **Default skill target:** `.claude/skills/` (use `--target github|agent|agents` for other tools).
- **Sample apps for reference:**
   - `maui/samples/Ailoha.Sample`
   - `android/samples/views`
   - `android/samples/compose`
   - `flutter/samples/ailoha_sample`
  - `react-native/samples/AilohaSampleRN`
  - `react-native/samples/AilohaSampleExpo`
  - `winui/samples/Ailoha.WinUI.Sample`
  - `wpf/samples/Ailoha.Wpf.Sample`

## Optional: extension authoring

If the project is a library and the user wants AI agents to interact with library-specific state, ship an Ailoha extension. The extension contributes routes under `/api/v1/ext/{namespace}/...` and shows up in `/api/v1/agent/capabilities`. See <https://ailoha.dev/docs/extensions.html> for per-platform code.

Namespaces must match `^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$` (reverse-DNS, lowercase).

## What to ask the user before editing

- Which platform's app is this? (only ask if you cannot determine from the file system)
- Should the agent be added only to debug builds? (default: yes — say so and proceed)

After you finish, leave the changes for the user to review and commit. Do not commit on their behalf unless they ask.

## Important docs

- [Docs index](https://ailoha.dev/docs/) — landing for all guides
- [AI-assisted setup](https://ailoha.dev/docs/ai-assisted.html) — the human-readable version of this file
- [Extensions guide](https://ailoha.dev/docs/extensions.html) — per-platform extension authoring
- [Protocol spec](https://ailoha.dev/docs/protocol.html) — DevFlow Agent Protocol (OpenAPI, AsyncAPI, JSON Schema)
- [OpenAPI reference](https://ailoha.dev/docs/api-reference.html) — Generated HTTP API reference
- [WebSocket reference](https://ailoha.dev/docs/ws-reference/) — Generated AsyncAPI channel reference
- [Protocol downloads](https://ailoha.dev/spec/v1/ailoha-devflow-agent-protocol-v1.zip) — Bundled specs, schemas, examples, manifest, and hashes