yaaf

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:

yaaf ask "Explain RAII in one sentence."

Ask through an OpenAI-compatible endpoint:

$env:YAAF_OPENAI_API_KEY = "sk-example"
yaaf ask --provider openai --model gpt-4o-mini "Explain RAII in one sentence."

Open a short chat:

yaaf chat "Reply with one short greeting."

Stream output as it arrives:

yaaf ask --stream "Write a haiku about C++."

Request JSON output for automation:

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:

yaaf doctor --format json --pretty

Simple Real-World Examples

Use a local script to add a tiny custom tool and run an agent:

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:

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:

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:

yaaf run ./examples/example.lua one two three

Start Here

• Usage: build output, environment variables, command reference, embeddings, and proxy setup.
• Examples: copyable CLI, Lua, ReAct, and MCP examples.
• Lua Runtime: how command modules and direct scripts are discovered and run.
• Lua API Reference: built-in runtime modules such as llm, tool, agent, and mcp.
• MCP Tools: explicit MCP config paths, supported config shape, and tool naming.
• Tool Reference: built-in tools and custom tool authoring.

Build And Detailed Setup

Build, environment setup, executable locations, and command reference live in Usage. The full documentation index is at 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: .\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. 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:

python -m pip install -r requirements-docs.txt
python -m mkdocs serve

Build the static docs site with:

python -m mkdocs build --strict

Implementation-level MCP protocol support details are maintained in libyaaf/mcp/README.md.