A plugin-based harness for LLMs in Rust that lives in your terminal: yak "fix the failing test" runs one task with tools (reading, editing, searching, running commands) and bare yak opens an interactive session. Sessions are stored as thread files and can be resumed anytime.
One binary, ~3 dependencies (ureq, serde_json, unicode-width), no async runtime, every other piece handwritten in-tree. Linux, macOS and Windows.
Linux and macOS download the prebuilt binary, verify its sha256 and install it with:
curl -fsSL https://jiaoyuan.org/yak/install.sh | shIt lands in ~/.local/bin, no root needed, and adds that directory to your PATH when missing. Windows does the same from PowerShell:
irm https://jiaoyuan.org/yak/install.ps1 | iexIt lands in %USERPROFILE%\.local\bin, no admin needed, and appends that directory to the user Path. Re-running either line is the updater: it checks the latest GitHub release, prints updating 0.2.1 -> 0.2.2 when it moves and leaves an unchanged version alone. YAK_FORCE=1 reinstalls anyway; YAK_VERSION pins a release tag, YAK_REPO installs from a fork and YAK_INSTALL_DIR picks a different directory. YAK_GH_PROXY=1 routes every download through https://gh-proxy.com/ for hosts where GitHub is slow or unreachable — any prefix-style p
8000
roxy URL works as the value too, and behind a proxy the latest-version lookup switches from the releases redirect to the GitHub API, which such proxies pass through. On Linux the static musl build is used, so the same binary runs on any distribution; prebuilt targets today are x86_64 and aarch64 Linux, x86_64 and aarch64 macOS, and x86_64 Windows.
Building from source works the same everywhere:
git clone https://github.com/imjiaoyuan/yak
cd yak
cargo build --releaseYou need a Rust toolchain (install one with rustup). The binary lands in target/release/yak (target\release\yak.exe on Windows): put it on your PATH. State lives under ~/.yak (%USERPROFILE%\.yak on Windows); set YAK_USER_PATH to relocate it. Requests to OpenCode's Go/Zen gateway carry a per-conversation x-opencode-session id; set YAK_SESSION_ID to pin one id across several yak invocations of the same conversation.
Linux, macOS and Windows all use the native platform implementation for the same terminal experience: raw-mode line editing, arrow-key pickers, hidden key input, and esc/ctrl-c interrupt while an agent task runs. Shell commands use sh on Linux/macOS and PowerShell on Windows by default; set YAK_SHELL to override the program (for example cmd, powershell, pwsh, bash, zsh, or any other shell on PATH). The interactive features need a real terminal; with piped stdin the CLI reads plain input.
The shortest version:
yak # open the interactive session
yak "fix the failing test" # run one task, then exit
cat error.log | yak "what broke?" # the prompt can come from stdinPiped output is plain text (no colours, no control codes) so it drops straight into a file or another command.
The first run needs a model: type /login, pick a provider from the shipped provider catalog (Anthropic, OpenAI, OpenCode Go, DeepSeek, MiniMax, Kimi Coding, Google, Groq, Mistral, xAI, OpenRouter, plus the local Ollama, LM Studio, llama.cpp and vLLM), paste the API key, pick the default model — or name the provider up front (/login openai) to skip the list and its prefilled questions. Or write the provider block into config.json by hand; see Providers and models.
/model switches the current session and saves the global default. Optional directory memory is handled by the model_pin extension when a task starts; existing directory pins still take precedence over the global default for new sessions.
Use /login openai-responses for the API-key Responses API; /login openai keeps Chat Completions. Custom providers can select responses too. /login google-native uses native Gemini (including signed tool history); /login google keeps Google’s OpenAI-compatible endpoint.
Attachments ride along natively (images, PDFs, audio, text) and in a session ctrl+v pastes the clipboard image straight into the prompt. Ask "remember this preference: ..." and the memory tool files it in ~/.yak/YAK.md, injected into every future session.
yak -a shot.png "what is wrong here?"
yak -a https://example.com/page "summarise this"The front page ends here. Everything else lives in docs/usage.md:
- The interactive session: slash commands, tab completion,
!cmd, interrupting a running task - Approvals and the blacklist: what is hardcoded, what you configure
- Tools: the surviving built-ins and the example-extension tools migrated off the registry
- Attachments: files, URLs, stdin, clipboard pastes
- Sessions: resume, fork, export,
--no-session - Session tree:
/treejumps that branch instead of truncating - Skills and prompt templates
- Providers and models:
/login, hand-edited config, aliases - Tuning the agent: tool policies, request caps, cache TTL, compaction
- The --json interface: drive
yakfrom an editor, CI lane or another agent - The --rpc control mode: a long-lived session steered over JSONL — prompts, steers and approvals from another process
- Plugins: script tools (Python, shell, Rust —
.rssources compile on first call), resident extensions, subagents, MCP
The plugin wire protocol has its own full reference: docs/extensions.md.
Packages bundle extensions, skills and prompt templates into one git repository and share it as a unit: yak install git:github.com/user/repo[@ref] clones into ~/.yak/pkg/<name> (-l installs project-local into .yak/pkg/, project winning over user; -g is the explicit default), and its extensions/, skills/ and commands/ directories mount into the normal discovery walks. A SKILL.md at the repository root counts too, as a single whole-repo skill: the shape most standalone skill repos ship (SKILL.md + references/ at the top), so yak install https://github.com/user/my-skill lands /skill:my-skill with no extra step. install reports what it recognized (skills, extensions, prompts); a repo carrying none of them is called out instead of mounting nothing silently.
Runnable examples of all kinds ship in this repo: examples/extensions/ (the six migrated agent surfaces — ls, plan (the former update_plan), search (grep+glob), memory (the former remember), webfetch, and skills itself (SKILL.md discovery, the <available_skills> block and every /skill:<name> command) — plus templates, an MCP bridge, subagents and more), examples/workflows/ (JSON graphs for the workflow.py orchestration extension — see its README), examples/skills/ (release-checklist, commit-hygiene, pkg-skill-audit — plain SKILL.md folders the skills extension mounts) and examples/agents/ (subagent definitions), and examples/commands/ (init, a prompt template that refreshes a repository's AGENTS.md from its current tree). Copy what you need; nothing mounts unless you install it.
Where the package goes is the only question: -l puts the clone in the project's .yak/pkg/, -g (the default) in ~/.yak/pkg/: a piped or CI install takes the same path, with nothing to prompt.
Re-running install refreshes a clone (git fetch + reset); a pinned @ref clone moves only via install repo@new-ref. yak list shows what each package carries, yak remove NAME deletes it. There is no npm lane: git only. Review any third-party package before installing: extensions run with full system access.
yak install git:github.com/user/yak-deploy # → ~/.yak/pkg/yak-deploy
yak install git:github.com/user/yak-deploy@v2 # pinned
yak install -l https://github.com/user/my-skill # project-local skill
yak list
yak remove yak-deployA plugin-based harness for LLMs in Rust
Usage:
yak [flags] [PROMPT]
Bare `yak` opens an interactive session; `yak "task"` runs one
agentic task with tools.
Available commands:
export Export a conversation as markdown (also: /export)
install Install a git package (also: remove, list)
threads List recent conversations (--all, --json, -n N)
Notable flags:
--rpc Long-lived JSONL control mode (commands in, events out)
--json One task as a JSON event stream
-r, --resume Browse past sessions and continue one
Flags:
-h, --help Show this message and exit
-v, --version Show the version number
Clone a package into the pkg directory (re-run to refresh)
Usage: yak install git:github.com/user/repo[@ref] [OPTIONS] SOURCE
Options:
-l, --local Install project-local (.yak/pkg/ instead of ~/.yak/pkg/)
-g, --global Install into the user directory (default)
-h, --help Show this message and exit
Export a conversation as markdown or self-contained HTML
Usage: yak export [OPTIONS] PATH
Options:
-h, --help Show this message and exit
--thread ID Thread id to export
--html Write one self-contained HTML file instead of markdown
Delete an installed package
Usage: yak remove NAME [OPTIONS]
Options:
-h, --help Show this message and exit
List installed packages and what they carry
Usage: yak list [OPTIONS]
Options:
-h, --help Show this message and exit
List recent conversations
Usage: yak threads [OPTIONS]
Options:
-h, --help Show this message and exit
-a, --all Every directory, not only this one
--json One JSON array of thread objects on stdout
-n, --limit N How many rows (default 20)
cargo build # debug build
cargo build --release
cargo test # inline #[cfg(test)] modules across the tree
YAK_USER_PATH=/tmp/x cargo run -- "smoke test prompt"The source is organized by role: src/commands/ holds one file per subcommand (flags, help, wiring), src/core/ the shared kernel (config, the thread store, http, rendering), src/providers/ one adapter per protocol plus the shared message model and the provider catalog, and the domains live top-level as agent/ and term/ (line editing, pickers, the spinner, terminal size). Tests are inline per module; run one with cargo test <name>.
Internal architecture (request path, agent loop, extension host, rendering) is documented in docs/architecture.md; the contributor guide is AGENTS.md.