Skip to main content

ZenAgent

PyPI CI Python

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, a headless one-shot, or your own program. Repo https://github.com/encyc/zen-agent · PyPI zenagent-py (imports as zenagent)

ZenAgent desktop in Coding mode: a session with tool rows and an inline diff

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:

provider env var
openai OPENAI_API_KEY
zai ZAI_API_KEY
zai-coding-cn ZAI_CODING_CN_API_KEY
deepseek DEEPSEEK_API_KEY
kimi KIMI_API_KEY
moonshotai, moonshotai-cn MOONSHOT_API_KEY
minimax MINIMAX_API_KEY
minimax-cn MINIMAX_CN_API_KEY
google GEMINI_API_KEY
xai XAI_API_KEY
openrouter OPENROUTER_API_KEY
xiaomi XIAOMI_API_KEY
xiaomi-token-plan-cn XIAOMI_TOKEN_PLAN_CN_API_KEY
xiaomi-token-plan-ams XIAOMI_TOKEN_PLAN_AMS_API_KEY
xiaomi-token-plan-sgp XIAOMI_TOKEN_PLAN_SGP_API_KEY
opencode-go OPENCODE_API_KEY

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 and 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 existed, so the Tauri desktop app reuses the same kernel instead of forking one — installers for macOS, Windows and Linux.
  • 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

What you get Where
A small kernel Five layers whose dependencies point strictly down; each layer is replaceable on its own architecture
Four surfaces TUI (transcript, tool cards, sidebar), REPL, headless one-shot, RPC/SDK CLI · TUI
Built-in tools files, bash with background jobs, grep/glob, web search + fetch, subagents, todo, project memory, LSP, GitHub, checkpoint/rewind (github registers only when gh is installed) tools
54 commands one slash-command surface shared by the TUI and the REPL, with Tab completion commands
Extend it skills, templates, extensions, MCP servers, custom providers — all file-driven extensions · MCP
Embed it Agent + subscribe in Python; zen rpc for every other language RPC & SDK
Desktop app A Tauri shell over the same zen rpc: sessions, work panel, approvals, self-update desktop

Desktop

The same kernel behind a Tauri shell: streaming tool cards, inline diffs, and a review and files work panel. Diffs and files stay beside the conversation.

The switcher above the session list decides how a project is run — the shot at the top of this page is Coding:

  • Coding — one session, one agent. You talk to it directly; it reads, edits and runs, and the work panel keeps diffs and files beside the conversation.
  • Zen — one router session per project. The router dispatches to background worker sessions, each with a focus and a status; their reports wake the router, which folds them into a single conversation.
  • Swarm — one room per project, one member per role. You and the roles post into the same feed: @role hands out a task, the report returns as a message, and the task index keeps the chain.

Zen mode: a router session with the worker roster in the sidebar Swarm mode: a project room with role agents, a task index and reports

Review panel with an inline diff

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:

Architecture The five layers and what one request touches
Slash commands All 54 commands
Configuration config.toml, providers, budgets
Contracts The invariants the kernel is built on
Development Gates, packaging check, releasing
Docs index Everything else, in reading order

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.

Metadata

Release files for zenagent-py 0.13.14

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zenagent-py 0.13.14
File Size Uploaded Provenance Actions
zenagent_py-0.13.14.tar.gz 631.0 kB Without provenance Details for zenagent_py-0.13.14.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zenagent-py 0.13.14
File Interpreter ABI Platform Actions
zenagent_py-0.13.14-py3-none-any.whl Python 3 none any Details for zenagent_py-0.13.14-py3-none-any.whl

Total release size: 1.4 MB

Release files / zenagent_py-0.13.14.tar.gz

Download URL zenagent_py-0.13.14.tar.gz
Size 631.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f92316882a7feb475e24adf7761c92cf74d19c1c8451ad3c4d0b902807e171a7
BLAKE2b-256 checksum
How to use checksums
620529ae2b7b34710692d65e8c409f126469fd714e054dd03af0dd6dac2d34f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / zenagent_py-0.13.14-py3-none-any.whl

Download URL zenagent_py-0.13.14-py3-none-any.whl
Size 771.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6015b8831a510163facf15c7657ba901dc001d03b5ebb084b05255f108291156
BLAKE2b-256 checksum
How to use checksums
b2770a8d5032204ec111299b55bfd154ccad37d8ebf8eacbbb9c67eaaef89a18
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for zenagent-py 0.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.13.14 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page