English | 简体中文
zycode is an open-source coding agent for your terminal and your editor. It speaks the standard Agent Client Protocol (ACP) over stdio, runs in the terminal (zypi), in VS Code (zycode.zycode), in Zed, or headlessly (-p), and is built on a modular Python agent runtime.
Website: zycode.dev (中文)
Unofficial project: this repository is not affiliated with, endorsed by, or maintained by the official pi project or its maintainers.
zypi (Rust TUI) / VS Code (zycode.zycode) / Zed & other ACP clients
│
ACP over stdio
▼
zycode-agent / pi-agent-cli-lc (ACP & headless CLI)
│
▼
pi-agent-harness-lc (sessions, compaction, skills)
│
▼
pi-agent-core-lc (agent loop, events, coding tools)
│
▼
LangChain StreamFn adapter (OpenAI / Anthropic / DeepSeek / gateways)
- Clients:
zypi(tui/): full-screen Rust terminal UI — vendored fork of grok-build (Apache-2.0) with allx.ai/*vendor extensions removed.zypihas no model client, tool runner, or MCP client; it talks to the agent over ACP.zycode.zycode(vscode/): VS Code / Open VSX extension with a chat view and thezycode-agentbinary bundled inside.- Any ACP editor or client (such as Zed or DeepSeek Harness).
- Coding Agent (
pi-agent-cli-lc) (packages/pi-agent-cli/): standard ACP stdio agent and headless-pCLI, also packaged as the standalonezycode-agentexecutable. - Extensions: optional Python packages for web search/fetch (
pi-web-access-py), goal planning (pi-goal-x-py), subagent workflows (pi-dynamic-workflows-py), and client-passed MCP servers (pi-mcp-py). - Underlying Python SDK: built on a faithful Python port of
pi-agent-corewith LangChain used strictly as aStreamFnboundary adapter. Full SDK documentation lives inpi_agent_core/README.md(agent loop, events, built-in coding tools, LangChain/MCP tool adapter, structured output, guardrails) andpackages/pi-agent-harness/README.md(AgentHarness, session tree storage, compaction, custom messages, skills,LocalExecutionEnv).
| Component | Status | Distribution |
|---|---|---|
zypi (Rust TUI) |
Stable | GitHub Releases (Linux x86_64 and aarch64, macOS arm64) |
zycode.zycode (VS Code extension) |
Stable | VS Code Marketplace and Open VSX (five platforms; the project owner tested the install of 1.0.0 and the update from 0.1.0 to 1.0.0 on Windows on 2026-11-12, and 1.4.0 with a real model on Windows on 2026-11-17 (the max level and the Context row); the rest of the Windows flow, macOS and Linux in a real VS Code are not verified) |
pi-agent-cli-lc |
Stable | PyPI |
pi-agent-core-lc |
Stable | PyPI |
pi-agent-harness-lc |
Stable | PyPI |
pi-web-access-py |
Stable | PyPI |
pi-goal-x-py |
Stable | PyPI |
pi-dynamic-workflows-py |
Stable | PyPI |
pi-mcp-py |
Stable | PyPI (from 0.6.0) |
- Standard ACP coding agent & headless CLI (
pi-agent-cli-lc)- Runs as a stdio ACP server for
zypi, VS Code, Zed, and other ACP clients — no vendor-specific RPCs. - Headless one-shot mode (
python -m pi_agent_cli -p "prompt") for scripting and CI; exits with status 1 and printserror: <reason>to stderr when a model call fails. - First-run interactive setup (
--setuporzypi --setup) writes model settings to~/.pi-python/agent.tomland stores API keys in~/.pi-python/local.env(never in TOML).PI_HOMErelocates the whole home directory. - Session commands (
/new,/resume,/quit),@directory listing, context compaction, and model switching (/model). - pi-aligned system prompt engine with tool contributions,
AGENTS.md/CLAUDE.mdcontext files,<available_skills>, and optional<git_status>snapshot (trusted projects only;--no-git-contextor[git] enabled = falseturns it off).
- Runs as a stdio ACP server for
- Full-screen Terminal UI (
zypi)- Interactive Rust TUI with session history, markdown rendering, Mermaid diagrams, and Shift+Tab permission-mode switching.
- Standalone release bundles (
zycode-<target>-<version>.tar.gz) shipzypiandzycode-agenttogether with zero Python dependencies required. - See TUI & Code-Agent Guide for full setup and usage.
- VS Code extension (
zycode.zycode)- Chat view with tool approval cards, Show diff for
write/edit, Past chats view, getting-started walkthrough, mode menu (Ask, Auto, Always approve), Thinking menu, and Context usage row (whencontext_windowis set inagent.toml). - Bundles
zycode-agentfor five platforms; seevscode/README.md.
- Chat view with tool approval cards, Show diff for
- Built-in coding tools & Python extensions
- Seven built-in coding tools:
read,edit,write,bash,grep,find, andls, with pi-faithful truncation limits and paging notices (seepi_agent_core/README.md). - Optional extensions: web search/fetch (
pi-web-access-py), goal planning (pi-goal-x-py), sandboxed subagent workflows (pi-dynamic-workflows-py), and MCP server bridge (pi-mcp-py, connectsstdio/http/sseservers passed by an ACP client asmcp__<server>__<tool>). - Extensions that fail to load are skipped and reported at session start rather than failing silently.
workflowon macOS: the script process has no kernel limit on memory or process count (measured in CI onmacos-15andmacos-15-intel), so only the audit hook stands in the way; Linux and Windows enforce kernel limits. Keepask(orauto, which also asks before everyworkflowcall) on macOS. Details:packages/pi-dynamic-workflows/README.md#macos-weaker-limits.
- Seven built-in coding tools:
- Three permission modes (
ask,auto,always-approve)ask(default): asks before any tool call unless the tool declares itself harmless (ToolAnnotations:readOnlyHint, or neither destructive nor open-world). Undeclared tools always ask.auto: runs read-only and clearly in-scope calls by rules and checks undecidedbashcalls with a model step (fails closed toask;[auto] classifier = "rules"disables the model step).always-approve: runs tool calls without prompting (also used by headless-pruns).- Auto is not a sandbox. Auto guards what a call writes or runs; it does not guard what a call reads or sends (
read,grep,find,ls,fetch_url,web_search, and recursive reads inbashrun without asking). Use a sandbox (zypi --sandbox, a container, or a VM) if you need an isolation boundary.
- Project trust
- Project-supplied extensions (
<project>/.pi-python/extensions), saved workflows (<project>/.pi-python/workflows),.pi/SYSTEM.md,.pi/APPEND_SYSTEM.md, project-relative skills, the<git_status>snapshot (which runsgitin the repository), andworkflowisolationworktrees load only for trusted projects. - Interactive ACP clients prompt once per directory and store a SHA-256 fingerprint of gated files in
~/.pi-python/agent/trust.json, asking again if any gated file changes. Configure statically via[extensions] trusted_projectsordefault_project_trust(ask/never/always) in~/.pi-python/agent.toml, or--trust-project-extensions/PI_TRUST_PROJECT_EXTENSIONS=1. Headless-pruns never ask but honour saved trust.
- Project-supplied extensions (
Download the standalone bundle (contains both zypi and zycode-agent; no Python required) or the standalone zypi binary for Linux (x86_64, aarch64) or macOS (arm64) from GitHub Releases:
# Option 1: Standalone bundle (zypi + zycode-agent; no Python required)
# Linux x86_64 shown. Other targets: zycode-linux-aarch64-1.0.0.tar.gz, zycode-darwin-aarch64-1.0.0.tar.gz.
curl -L -o zycode.tar.gz https://github.com/zy1233/pi-python/releases/download/v1.0.0/zycode-linux-x86_64-1.0.0.tar.gz
tar -xzf zycode.tar.gz
sudo mv zypi zycode-agent /usr/local/bin/
# Set up model and API key in your terminal, then start:
zypi --setup
zypiThe bundle file name holds the version, so the URL names the tag (v1.0.0), not latest.
# Option 2: zypi binary alone with the Python pip package
curl -L -o zypi https://github.com/zy1233/pi-python/releases/latest/download/zypi-linux-x86_64
chmod +x zypi
sudo mv zypi /usr/local/bin/
# Tell zypi which Python has pi-agent-cli-lc installed:
export PI_PYTHON=python3
zypi --setupOr build zypi from source (requires Rust toolchain; on Windows, build and run in WSL2):
cd tui && cargo build --profile release-dist -p pi-pager-bin
# binary at target/release-dist/zypiSee TUI & Code-Agent Guide and Windows notes for platform details (glibc 2.39+ on Linux, unsigned macOS builds, WSL2 setup).
The extension zycode.zycode (vscode/README.md) puts the zycode agent in a chat view in VS Code with the agent binary bundled inside (no separate Python install needed). It is unofficial and not affiliated with pi or Microsoft.
- VS Code: install from the Visual Studio Marketplace, or run
code --install-extension zycode.zycode. - VSCodium / Open VSX: install from Open VSX.
- Platforms:
linux-x64,linux-arm64,darwin-arm64,darwin-x64, andwin32-x64. - Limits: the bundled agent is not code-signed and includes only the OpenAI-format provider (for Anthropic or DeepSeek providers, install
pi-agent-cli-lcand setzycode.agentPath). The project owner tested installing 1.0.0 and updating from 0.1.0 to 1.0.0 on Windows (2026-11-12), and ran 1.4.0 with agent 1.0.0 and a real model on Windows (2026-11-17:maxthinking level and the Context row after settingcontext_windowinagent.toml). The rest of the Windows flow, all macOS flows, and Linux in a real VS Code are not verified. Release record:vscode/RELEASING.md.
Because the agent speaks ACP over stdio, Zed can run it as a custom agent. Install uv, then add this entry to Zed's settings.json:
{
"agent_servers": {
"pi-python": {
"type": "custom",
"command": "uvx",
"args": [
"--from", "pi-agent-cli-lc",
"--with", "pi-agent-core-lc[deepseek]",
"pi-agent-cli"
],
"env": {}
}
}
}--withinstalls the LangChain provider package ([openai]or[anthropic]for those providers).- First run: Zed offers the terminal login "Set up model and API key" (runs
--setupin a terminal to write~/.pi-python/agent.tomland~/.pi-python/local.env), or runuvx --from pi-agent-cli-lc --with "pi-agent-core-lc[deepseek]" pi-agent-cli --setupdirectly in a shell. (The Zed login dialog was verified with a scripted ACP client, not yet inside Zed itself.) - To configure manually, start from
packages/pi-agent-cli/agent.example.tomland supply the API key via environment variables or~/.pi-python/local.env(never insideagent.toml). - To run from a local checkout, set
commandto your venv Python andargsto["-m", "pi_agent_cli"].
# Install the coding agent CLI + a provider:
pip install pi-agent-cli-lc
pip install "pi-agent-core-lc[openai]" # or [anthropic], [deepseek]
# First-run interactive configuration:
python -m pi_agent_cli --setup
# Headless one-shot prompt (for scripts & CI):
python -m pi_agent_cli -p "Explain this codebase" --cwd /path/to/project
# Optional extensions:
pip install pi-web-access-py # web search & URL fetch
pip install pi-goal-x-py # goal-driven planning (/goal)
pip install pi-dynamic-workflows-py # subagent workflow orchestration
pip install pi-mcp-py # MCP servers passed by an ACP editorUsing the underlying Python agent loop or harness as a library? See pi_agent_core/README.md and packages/pi-agent-harness/README.md.
Development install (editable)
pip install -e ".[dev]"
pip install -e "./packages/pi-agent-harness"
pip install -e "./packages/pi-agent-cli"
pip install -e "./packages/pi-web-access"
pip install -e "./packages/pi-goal-x"
pip install -e "./packages/pi-dynamic-workflows"
pip install -e "./packages/pi-mcp"zycode can also run inside DeepSeek Harness (dsh) as a delegated ACP subagent (@deepseek-ai/dsh-subagent-acp) or as a full session via the third-party community plugin (@zaimokuza/dsh-acp-adapter). See docs/DEEPSEEK-HARNESS.md for setup, permission/trust caveats, and verification scope.
Evaluated on FrontierHarness 30 (21 Terminal-Bench + 9 DeepSWE tasks across Windows local and WSL2 Docker sandbox runtimes), including a side-by-side comparison with official Pi and documented methodology caveats.
Full report: FRONTIER-HARNESS-30-EVAL-REPORT.md.
# Python tests (no API keys required; real_llm tests are excluded by default)
uv run --extra dev --extra harness python -m pytest
ruff check . && ruff format --check .
# Rust TUI check (Linux / WSL2)
cd tui && cargo check -p pi-pager-bin
# VS Code extension check
cd vscode && npm run checkFor real-LLM regression tests, the weekly provider matrix, and smoke scripts, see pi_agent_core/README.md#testing. For contributor conventions and invariants, see AGENTS.md.
| Document | Contents |
|---|---|
| TUI & Code-Agent Guide | Installation, configuration, and usage for zypi TUI and pi-agent-cli-lc |
| VS Code extension | zycode.zycode features, permissions, thinking menu, settings, and limits |
| ACP CLI package | pi-agent-cli-lc entry points, headless flags, config, and setup |
| Core runtime & coding tools | pi-agent-core-lc: agent loop, LangChain adapter, structured output, guardrails, coding tools, events, pi concept mapping |
| AgentHarness runtime | pi-agent-harness-lc: sessions, compaction, custom messages, skills, LocalExecutionEnv |
| DeepSeek Harness guide | Running zycode in DeepSeek Harness (subagent and community ACP adapter) |
| Windows notes | Windows setup, WSL2 TUI build, spawn/config notes |
| Benchmark report | FrontierHarness 30-task evaluation & Pi comparison |
| Architecture & specs | Project-wide architecture; detailed phase specs in docs/specs/ and audits in docs/AUDIT/ |
| AGENTS.md | Repository map, invariants, and development workflows |
Core runtime, AgentHarness, coding tools, ACP CLI, zypi TUI, VS Code extension, and extension packages are all released at 1.0.0 (see CHANGELOG.md for the full history).
Next:
- TUI platform expansion — planned, no date: a prebuilt
zypibinary for Windows. There is no macOSx86_64build ofzypiand none is planned, and there is no automatic update.
Python packages (pi-agent-core-lc, pi-agent-harness-lc, pi-agent-cli-lc, and extension packages) and the VS Code extension (vscode/) are MIT.
The tui/ directory is a vendored fork of xai-org/grok-build and remains Apache License 2.0. See tui/LICENSE, tui/NOTICE, and tui/THIRD-PARTY-NOTICES. tui/ is not included in Python sdists or wheels.