# yaaf
[](https://github.com/svnscha/yaaf/actions/workflows/ci.yml)
[](https://svnscha.github.io/yaaf/)
[](https://github.com/svnscha/yaaf/stargazers)
[](https://github.com/svnscha/yaaf/actions/workflows/ci.yml)
Yaaf is a command-line runtime for small AI workflows in Lua. You can use it as a normal CLI for prompts and chat, wire in local or MCP tools, or run a Lua script that registers its own tools and agents.
The native layer handles startup, HTTP, JSON, and MCP transports. Lua handles commands, tools, agents, and provider logic, so you can start with copyable commands and then grow into custom workflows without changing runtimes.
Current development and CI support cover Windows, macOS, and Linux. The Linux release artifact is built as a musl-based static binary so the packaged `yaaf` runtime stays portable across mainstream Linux distributions. CI validates the packaged Linux bundle with the shipped `lua/` and `examples/` directories and smoke-tests it on both Alpine and Debian.
## What It Is Good At
- One-shot prompts from the terminal.
- Chat sessions with local or remote models.
- Tool-using agents with a small Lua surface area.
- MCP-backed tools loaded from a VS Code-style `mcp.json`.
- Direct Lua scripts that register local tools for a single run.
## Quick Start
When MCP is configured, `yaaf doctor` now performs an active initialize and `tools/list` check for each server and reports the discovered tool names or a failure reason.
These examples assume `yaaf` is already built and the build output directory is on `PATH`.
Ask a quick question:
```powershell
yaaf ask "Explain RAII in one sentence."
```
Ask through an OpenAI-compatible endpoint:
```powershell
$env:YAAF_OPENAI_API_KEY = "sk-example"
yaaf ask --provider openai --model gpt-4o-mini "Explain RAII in one sentence."
```
Open a short chat:
```powershell
yaaf chat "Reply with one short greeting."
```
Stream output as it arrives:
```powershell
yaaf ask --stream "Write a haiku about C++."
```
Request JSON output for automation:
```powershell
yaaf ask --format json --pretty "Return a JSON object with answer equal to 2."
```
Inspect your current runtime configuration and actively probe configured MCP servers:
```powershell
yaaf doctor --format json --pretty
```
## Simple Real-World Examples
Use a local script to add a tiny custom tool and run an agent:
```powershell
yaaf run ./examples/weather_agent.lua "Use the weather tool to tell me the weather in Berlin."
```
Use the built-in echo tool to verify agent tool wiring before involving external services:
```powershell
yaaf agent --name react --tool echo "Use the echo tool to repeat hello."
```
Point yaaf at an explicit MCP config and call a remote tool:
```powershell
yaaf ask --mcp ./configs/docs.mcp.json --tool docs.lookup "Look up the install steps."
```
Run a Lua script directly when you want full control over the workflow:
```powershell
yaaf run ./examples/example.lua one two three
```
## Start Here
- [Usage](https://svnscha.github.io/yaaf/usage/): build output, environment variables, command reference, embeddings, and proxy setup.
- [Examples](https://svnscha.github.io/yaaf/examples/): copyable CLI, Lua, ReAct, and MCP examples.
- [Lua Runtime](https://svnscha.github.io/yaaf/lua/): how command modules and direct scripts are discovered and run.
- [Lua API Reference](https://svnscha.github.io/yaaf/modules/): built-in runtime modules such as `llm`, `tool`, `agent`, and `mcp`.
- [MCP Tools](https://svnscha.github.io/yaaf/mcp/): explicit MCP config paths, supported config shape, and tool naming.
- [Tool Reference](https://svnscha.github.io/yaaf/tools/): built-in tools and custom tool authoring.
## Build And Detailed Setup
Build, environment setup, executable locations, and command reference live in [Usage](https://svnscha.github.io/yaaf/usage/). The full documentation index is at [https://svnscha.github.io/yaaf/](https://svnscha.github.io/yaaf/).
Start from a clone with the vendored vcpkg submodule initialized: `git clone --recurse-submodules https://github.com/svnscha/yaaf.git` or `git submodule update --init --recursive` in an existing clone. Then bootstrap `./vcpkg` before the first configure.
For Windows development builds, use the checked-in presets from [Usage](https://svnscha.github.io/yaaf/usage/): `.\vcpkg\bootstrap-vcpkg.bat`, then `cmake --preset windows-x64`, then `cmake --build --preset windows-debug` or `cmake --build --preset windows-release`.
For macOS and Linux contributor builds, bootstrap the vendored submodule with `./vcpkg/bootstrap-vcpkg.sh`, then run `cmake -S . -B build -G Ninja && cmake --build build`.
For the Linux release path, use the musl static preset documented in [Usage](https://svnscha.github.io/yaaf/usage/). The validated local reproduction command is `git submodule update --init --recursive && ./vcpkg/bootstrap-vcpkg.sh && cmake --preset linux-musl-static && cmake --build build/linux-musl-static --config Release --target yaaf`.
Serve the docs locally with MkDocs:
```powershell
python -m pip install -r requirements-docs.txt
python -m mkdocs serve
```
Build the static docs site with:
```powershell
python -m mkdocs build --strict
```
Implementation-level MCP protocol support details are maintained in [libyaaf/mcp/README.md](libyaaf/mcp/README.md).