8000 GitHub - imjiaoyuan/yak: A plugin-based harness for LLMs in Rust. · GitHub
[go: up one dir, main page]

Skip to content
imjiaoyuanPublic

About

A plugin-based harness for LLMs in Rust.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Latest commit

 

History

563 Commits

Folders and files

Repository files navigation

yak

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.

Install

Linux and macOS download the prebuilt binary, verify its sha256 and install it with:

curl -fsSL https://jiaoyuan.org/yak/install.sh | sh

It 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 | iex

It 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 --release

You 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.

Platform notes

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.

Usage

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 stdin

Piped 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"

Going deeper

The front page ends here. Everything else lives in docs/usage.md:

The plugin wire protocol has its own full reference: docs/extensions.md.

Packages

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-deploy

Help

A 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)

Development

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.

About

A plugin-based harness for LLMs in Rust.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0