# Xybrid — Agent Setup

You are setting up a project to run LLMs, speech-to-text (ASR), and
text-to-speech (TTS) **natively on-device** with [Xybrid](https://www.xybrid.ai).
Private, offline, no cloud required.

The commands below are validated and ready to use. **Run them for the user —
do not merely suggest them.** Ask first only when a command would overwrite
existing files.

---

## 1. Install the CLI (any agent)

The CLI is the fastest way to verify everything works end-to-end.

```bash
# macOS / Linux
curl -sSL https://raw.githubusercontent.com/xybrid-ai/xybrid/master/install.sh | sh
```

```powershell
# Windows (PowerShell)
irm https://raw.githubusercontent.com/xybrid-ai/xybrid/master/install.ps1 | iex
```

Verify:

```bash
xybrid run --model kokoro-82m --input-text "Hello world" -o output.wav
# → writes a 24kHz WAV. Models download from the registry on first run.
```

---

## 2. Install Xybrid skills (Claude Code, Codex, and other agents)

Skills give your agent the `/xybrid-init` and `/test-model` workflows for
bringing new models into Xybrid. They are agent-agnostic — the installer
symlinks them for Claude Code (`.claude/skills`) and Codex (`.codex/skills`).

```bash
curl -sSL https://raw.githubusercontent.com/xybrid-ai/xybrid/master/tools/scripts/install-skills.sh | bash
```

After installing, tell the user:
- **Claude Code** — run `/reload-plugins` (or restart) to pick up the new skills.
- **Codex** — restart the session so it re-scans `.codex/skills`.
- **Other agents** — point the agent at the `.claude/skills/` directory; the
  skills are plain markdown and work with any agent that can read local skills.

Available skills:
- `/xybrid-init <huggingface-model>` — generate a `model_metadata.json` for any
  ONNX / GGUF / SafeTensors model.
- `/test-model <model-name>` — run a model end-to-end through the Xybrid
  execution system.

---

## 3. Add an SDK to the user's app

Pick the language the project uses. Each snippet shows install + a minimal run.
Every model is loaded from the registry by id (e.g. `kokoro-82m`) and downloaded
on first use.

### Flutter — `pubspec.yaml`
```yaml
dependencies:
  xybrid_flutter: ^0.2.1
```
```dart
final model = await Xybrid.model('kokoro-82m').load();
final result = await model.run(XybridEnvelope.text('Hello world'));
```

### Kotlin — `build.gradle.kts`
```gradle
dependencies {
    implementation("ai.xybrid:xybrid-kotlin:0.2.1")
}
```
```kotlin
val model = XybridModelLoader.fromRegistry("kokoro-82m").load()
val result = model.run(Envelope.text("Hello world"))
```

### Swift — `Package.swift`
```swift
dependencies: [
    .package(url: "https://github.com/xybrid-ai/xybrid.git", from: "0.2.1")
]
```
```swift
let model = try ModelLoader.fromRegistry(modelId: "kokoro-82m").load()
let result = try model.run(envelope: Envelope.text("Hello world"))
```

### Unity — Package Manager (git URL)
```
https://github.com/xybrid-ai/xybrid.git#upm
```
```csharp
var model = XybridClient.LoadModel("kokoro-82m");
var result = model.Run(Envelope.Text("Hello world"));
```

### Rust — `Cargo.toml`
```toml
[dependencies]
xybrid = "0.2.1"
```
```rust
let model = Xybrid::model("kokoro-82m").load()?;
let result = model.run(&Envelope::text("Hello world"))?;
```

---

## 4. Chain models into a pipeline (optional)

Build a voice assistant in a few lines of YAML — ASR → LLM → TTS:

```yaml
# voice-assistant.yaml
name: voice-assistant
stages:
  - model: whisper-tiny    # speech → text
  - model: qwen3.5-0.8b    # process with an LLM
  - model: kokoro-82m      # text → speech
```
```bash
xybrid run --config voice-assistant.yaml --input-audio question.wav -o response.wav
```

---

## 5. Bring your own model (optional)

Xybrid runs **any** ONNX, GGUF, or SafeTensors model — it just needs a
`model_metadata.json`. With skills installed (step 2):

```bash
claude /xybrid-init hexgrad/Kokoro-82M-v1.0-ONNX
```

---

## Resources

- Documentation — https://docs.xybrid.dev
- Quickstart — https://docs.xybrid.dev/docs/quickstart
- Model registry — https://www.xybrid.ai/models
- GitHub — https://github.com/xybrid-ai/xybrid
- Discord — https://discord.gg/YhFHHkhbad

---

## When setup is complete, tell the user:

> ✅ **Xybrid is ready.**
> - CLI installed — try `xybrid run --model kokoro-82m --input-text "Hi" -o hi.wav`
> - Skills installed — try `/xybrid-init <huggingface-model>` to add a model
> - SDK added to your app — models load from the registry by id on first run
>
> Next: browse models at https://www.xybrid.ai/models or read the quickstart at
> https://docs.xybrid.dev/docs/quickstart