zy-agent

A local coding agent and terminal chat for ZY-S1, ZYR AI's small code model. It runs entirely on your CPU with zy-engine, a PrefixLM-aware inference engine built on llama.cpp. No API key and no GPU needed.

npx zy-agent                 # coding agent in the current directory
npm i -g zy-agent            # or install the commands globally:
zy-agent                     #   coding agent (terminal UI)
zy-agent -C path/to/project  #   ...in another folder
zy-chat                      #   plain chat with ZY-S1 (terminal UI)
zy-agent --help

On first run the launcher creates a private Python environment in ~/.zy/venv and installs the bundled zy-engine package there. It then downloads the model (zyr-AGENT/ZY-S1-GGUF, Q4_K_M, about 740 MB) from Hugging Face. Later runs start right away.

Requirements

• Node.js 16 or newer, plus Python 3.9+ with the venv module (sudo apt install python3 python3-venv on Debian/Ubuntu). Set ZY_PYTHON to use a specific interpreter.
• Linux x86_64 with glibc 2.38 or newer (Ubuntu 24.04+, Debian 13+, Fedora 39+): a prebuilt engine is bundled.
• Other platforms and older Linux: the engine is compiled from the bundled source on first run. This needs CMake 3.18 or newer and a C++17 compiler (Xcode command line tools on macOS; Visual Studio Build Tools on Windows). The launcher tells you if anything is missing.
• About 3 GB of free RAM.

What the agent does

You describe a task, for example "calc.py prints the wrong average. Fix the bug; python calc.py should print 4.0". The agent then works step by step with these tools: list_dir, read_file, search, write_file, run_shell, done.

• Approvals are on by default. Every file write shows a diff and every shell command is shown first, and each waits for y/n. --yes turns approvals off; only use it in throwaway folders.
• Limits: at most 8 steps (--max-steps), commands time out after 60 s, and files outside the project folder can't be touched.
• How steps are chosen: ZY-S1 has no native tool calling. Its output is constrained instead: zy-engine scores every action that is valid right now by log-likelihood, and the model's top choice is taken. The UI labels each step "ZY-S1" or "only option".
• How edits are made: ZY-S1 rewrites the failing function. Up to 8 candidates are tested in a throwaway copy of your project, and only a passing edit is offered. If none passes, the agent tries small rule-based fixes such as off-by-one, comparison or operator flips. Those are labelled as not written by ZY-S1, and the final summary says for every edit whether ZY-S1 or the rule-based fallback wrote it.
• Tests: the agent fixes your code, not your tests: test files and the check script are not edited unless you ask for it. If your project has test_*.py files but pytest is not installed, the agent runs them with a small built-in runner (every test_* function and unittest case) and tells you so. If the check command can't run at all (for example the tool isn't installed), the agent says so instead of blaming the edit, and marks the result as not verified.
• Typing while it works: pressing Enter during a run queues your next task (or chat message); it starts when the current one finishes. Esc stops the current run and drops the queue.

Honest note. ZY-S1 is a small (~1B) preview model. It handles small, local fixes in small projects, such as one-function bugs and tiny new scripts, and simple questions about code. Don't expect multi-file features or refactors. Always review the diffs.

Keys

| Key | Action | | --- | --- | | Enter | send | | Esc | stop | | Ctrl+T | switch agent/chat | | Ctrl+S | settings | | Ctrl+Y | copy last answer | | Ctrl+L | clear | | Ctrl+R | reset the chat (agent tasks always start fresh) | | F1 | help | | Ctrl+C | quit |

Options

zy-agent [MODEL] [-C DIR] [--yes] [--max-steps N] [-t THREADS] [-c CTX] [--temp T] [--url http://127.0.0.1:8080/v1]

• MODEL is a Hugging Face repo id or a local .gguf file.
• --url reuses a zy-engine server that is already running.
• --zy-reinstall rebuilds ~/.zy/venv. ZY_HOME moves ~/.zy somewhere else.

License: Apache-2.0