ZenAgent

English · 简体中文

A coding agent you can read, embed and change: one pure-Python kernel, one runtime dependency (httpx), four ways to drive it. It reads and edits files, runs commands, searches the web, delegates to read-only subagents and keeps a project todo list — from a terminal, from a headless one-shot, or from your own program.

Repo https://github.com/encyc/zen-agent · PyPI zenagent-py (imports as zenagent)

Install

uv tool install "zenagent-py[cli]"   # or: pip install "zenagent-py[cli]"
zen --version

Python 3.11+ (3.11–3.14 ship). A kernel-only install (pip install zenagent-py) gives you the SDK without the terminal UI.

API keys are read from the environment, named per provider in zenagent/catalog.yaml:

Overseas and China endpoints are separate providers sharing one key (moonshotai / moonshotai-cn). Token-plan endpoints (zai-coding-cn, xiaomi-token-plan-*) bill 0.

A [providers.custom.<id>] table points the same kernel at any OpenAI-compatible endpoint, a local server included — see configuration.

First run

zen                                     # TUI: transcript, tool cards, sidebar
zen -p "explain this repo" --json       # headless: one JSON object, CI-friendly

The TUI checks PyPI at most once an hour and prints one line when a newer release exists; -p/--json never check. ZENAGENT_NO_UPDATE_CHECK=1 turns it off.

What this is, and why

Coding agents are either closed and vendor-tied, or large enough that changing one layer means reading ten. ZenAgent is the small one: a Python kernel you can read in an evening, embed in an afternoon, and change without permission.

• One dependency. types, events, providers, agent and tools import httpx and nothing else. The wheel is ~440 KB; zen --version takes ~0.1 s.
• Pure Python. No node runtime, no build step, no daemon in the middle — pip install, then run it.
• One kernel, four surfaces. TUI, REPL, headless (-p/--json) and zen rpc (a JSONL protocol) all drive the same runtime the same way.
• A GUI is a client, not a rewrite. The RPC surface already exists, so the planned Tauri app is coming.
• Embed it in 30 lines. Agent(model=..., tools=..., api_key=...) plus one subscribe callback: your tools, your storage, your event loop.
• Extend without restarting. Skills, prompt templates, extensions, MCP servers and custom providers are all files; /reload picks them up mid-session.
• No vendor lock-in. Two protocol adapters (openai-completions, including the zai/deepseek dialects, and anthropic-messages) plus a packaged catalog carrying prices and context windows.
• Costs you can see. zen usage, /usage, per-request cost in the transcript, and --max-cost as a hard stop.

Features

Contributing

uv sync --extra cli      # kernel + terminal UI + dev tools
bash scripts/check.sh    # the only gate: sync + ruff + pytest (CI runs exactly this)

The package supports 3.11+, but the repository pins .python-version to 3.15 — that is the uv toolchain, not the floor users need.

Where to read next:

Not done: OS-level sandboxing. The workspace fence and write snapshots protect against agent mistakes, not against a malicious repository or prompt injection.

MIT licensed — see LICENSE.