{"id":51297927,"url":"https://github.com/svnscha/yaaf","last_synced_at":"2026-06-30T16:30:40.000Z","repository":{"id":359855192,"uuid":"1245320775","full_name":"svnscha/yaaf","owner":"svnscha","description":"Yaaf is a command-line runtime for small AI workflows in Lua.","archived":false,"fork":false,"pushed_at":"2026-05-23T20:02:22.000Z","size":205,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T20:24:01.449Z","etag":null,"topics":["ai","cpp","cross-platform","llm","lua","ollama-client","openai-client","osx","runtime","windows","yaaf"],"latest_commit_sha":null,"homepage":"https://svnscha.github.io/yaaf/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/svnscha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-21T05:47:36.000Z","updated_at":"2026-05-23T20:02:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/svnscha/yaaf","commit_stats":null,"previous_names":["svnscha/yaaf"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/svnscha/yaaf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svnscha%2Fyaaf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svnscha%2Fyaaf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svnscha%2Fyaaf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svnscha%2Fyaaf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/svnscha","download_url":"https://codeload.github.com/svnscha/yaaf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svnscha%2Fyaaf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34975668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cpp","cross-platform","llm","lua","ollama-client","openai-client","osx","runtime","windows","yaaf"],"created_at":"2026-06-30T16:30:39.481Z","updated_at":"2026-06-30T16:30:39.990Z","avatar_url":"https://github.com/svnscha.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# yaaf\n\n[![CI](https://github.com/svnscha/yaaf/actions/workflows/ci.yml/badge.svg)](https://github.com/svnscha/yaaf/actions/workflows/ci.yml)\n[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://svnscha.github.io/yaaf/)\n[![GitHub stars](https://img.shields.io/github/stars/svnscha/yaaf?style=social)](https://github.com/svnscha/yaaf/stargazers)\n[![Platforms](https://img.shields.io/badge/platforms-windows%20%7C%20macOS%20%7C%20Linux-0a7ea4)](https://github.com/svnscha/yaaf/actions/workflows/ci.yml)\n\nYaaf 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.\n\nThe 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.\n\nCurrent 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.\n\n## What It Is Good At\n\n- One-shot prompts from the terminal.\n- Chat sessions with local or remote models.\n- Tool-using agents with a small Lua surface area.\n- MCP-backed tools loaded from a VS Code-style `mcp.json`.\n- Direct Lua scripts that register local tools for a single run.\n\n## Quick Start\n\nWhen 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.\n\n\nThese examples assume `yaaf` is already built and the build output directory is on `PATH`.\n\nAsk a quick question:\n\n```powershell\nyaaf ask \"Explain RAII in one sentence.\"\n```\n\nAsk through an OpenAI-compatible endpoint:\n\n```powershell\n$env:YAAF_OPENAI_API_KEY = \"sk-example\"\nyaaf ask --provider openai --model gpt-4o-mini \"Explain RAII in one sentence.\"\n```\n\nOpen a short chat:\n\n```powershell\nyaaf chat \"Reply with one short greeting.\"\n```\n\nStream output as it arrives:\n\n```powershell\nyaaf ask --stream \"Write a haiku about C++.\"\n```\n\nRequest JSON output for automation:\n\n```powershell\nyaaf ask --format json --pretty \"Return a JSON object with answer equal to 2.\"\n```\n\nInspect your current runtime configuration and actively probe configured MCP servers:\n\n```powershell\nyaaf doctor --format json --pretty\n```\n\n## Simple Real-World Examples\n\nUse a local script to add a tiny custom tool and run an agent:\n\n```powershell\nyaaf run ./examples/weather_agent.lua \"Use the weather tool to tell me the weather in Berlin.\"\n```\n\nUse the built-in echo tool to verify agent tool wiring before involving external services:\n\n```powershell\nyaaf agent --name react --tool echo \"Use the echo tool to repeat hello.\"\n```\n\nPoint yaaf at an explicit MCP config and call a remote tool:\n\n```powershell\nyaaf ask --mcp ./configs/docs.mcp.json --tool docs.lookup \"Look up the install steps.\"\n```\n\nRun a Lua script directly when you want full control over the workflow:\n\n```powershell\nyaaf run ./examples/example.lua one two three\n```\n\n## Start Here\n\n- [Usage](https://svnscha.github.io/yaaf/usage/): build output, environment variables, command reference, embeddings, and proxy setup.\n- [Examples](https://svnscha.github.io/yaaf/examples/): copyable CLI, Lua, ReAct, and MCP examples.\n- [Lua Runtime](https://svnscha.github.io/yaaf/lua/): how command modules and direct scripts are discovered and run.\n- [Lua API Reference](https://svnscha.github.io/yaaf/modules/): built-in runtime modules such as `llm`, `tool`, `agent`, and `mcp`.\n- [MCP Tools](https://svnscha.github.io/yaaf/mcp/): explicit MCP config paths, supported config shape, and tool naming.\n- [Tool Reference](https://svnscha.github.io/yaaf/tools/): built-in tools and custom tool authoring.\n\n## Build And Detailed Setup\n\nBuild, 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/).\n\nStart 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.\n\nFor 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`.\n\nFor macOS and Linux contributor builds, bootstrap the vendored submodule with `./vcpkg/bootstrap-vcpkg.sh`, then run `cmake -S . -B build -G Ninja \u0026\u0026 cmake --build build`.\n\nFor 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 \u0026\u0026 ./vcpkg/bootstrap-vcpkg.sh \u0026\u0026 cmake --preset linux-musl-static \u0026\u0026 cmake --build build/linux-musl-static --config Release --target yaaf`.\n\nServe the docs locally with MkDocs:\n\n```powershell\npython -m pip install -r requirements-docs.txt\npython -m mkdocs serve\n```\n\nBuild the static docs site with:\n\n```powershell\npython -m mkdocs build --strict\n```\n\nImplementation-level MCP protocol support details are maintained in [libyaaf/mcp/README.md](libyaaf/mcp/README.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvnscha%2Fyaaf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsvnscha%2Fyaaf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvnscha%2Fyaaf/lists"}