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
48 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 48 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.5

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.5
File Size Uploaded Provenance Actions
zenagent_py-0.13.5.tar.gz 547.6 kB Without provenance Details for zenagent_py-0.13.5.tar.gz

Built distribution (wheel)

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

Total release size: 1.2 MB

Release files / zenagent_py-0.13.5.tar.gz

Download URL zenagent_py-0.13.5.tar.gz
Size 547.6 kB
Tags Source
SHA-256 checksum
How to use checksums
1fe5de295e618e8fe219e76471d6f906b102c791c9afdf0f1bc83189532be1bc
BLAKE2b-256 checksum
How to use checksums
899bfb235ece84e9c3e96cff3f50a8fef52cfc2212c7977daca699b849e2a745
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.5-py3-none-any.whl

Download URL zenagent_py-0.13.5-py3-none-any.whl
Size 671.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2be433efcc205a07a0b271a8e1a231d296c5077940dffa2e9b76f24fae849890
BLAKE2b-256 checksum
How to use checksums
803fbd6fc48d33be8218d16316dcd55f2ce8637083e590e270094d1110970d6d
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.5

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