In beta Open source · MIT and Apache-2.0

A coding agent you can audit.

zycode runs a small agent loop with a written contract. Every turn and every tool call is an event that you can log and test. Use it in your terminal, or in any editor that speaks ACP.

Get started View on GitHub

Install the agent

pip install pi-agent-cli-lc

Today the project ships as zypi (the terminal UI) and pi-agent-cli-lc (the agent).

zypi ~/shop-api beta

› The checkout test fails on rounding. Find the cause and fix it.

read tests/test_checkout.py read-only · no prompt

grep "round(" src/ read-only · no prompt

read src/checkout/totals.py read-only · no prompt

The totals use float. round(2.675, 2) gives 2.67, because 2.675 has no exact float form. Use Decimal with ROUND_HALF_UP.

edit src/checkout/totals.py +6 −3 asked · you allowed

bash pytest tests/test_checkout.py 14 passed asked · you allowed

Done. The checkout tests pass.

›

Illustration. This is not a recording.

01 Why

Built to be checked, not trusted.

A coding agent changes your files and runs your commands. zycode makes each of these steps visible, limited and testable.

A written event contract

Each run emits the same events in the same order. Tests keep that order fixed. You can log the events and build on them.
One protocol, any client

The agent speaks the Agent Client Protocol (ACP) over stdio, with no vendor-specific calls. The terminal UI, Zed and other ACP clients start the same process.
A UI with no model client

zypi has no model client, no tool runner and no MCP client. The Python agent does that work. An audit of one real turn found no connection from zypi to an address outside the machine.
Permission by declaration

In ask mode, the agent asks before a tool call unless the tool declares that it is harmless. A tool that declares nothing is asked about.
Project trust

A project can ship extensions, workflows, prompts and skills. The agent loads them only after you trust the project. It asks again when one of those files changes.
Any model, one loop

LangChain is only the boundary to the model. The loop, the tools and the events stay in our code. Use OpenAI, Anthropic, DeepSeek or an OpenAI-compatible gateway.

02 Contract

The same events, every run.

The core loop is a faithful port of the agent loop of the pi project. Its event protocol is a contract, and tests enforce it.

One turn with a tool call

agent_start The run starts.
turn_start A turn starts.
message_start · message_end The user message.
message_start The assistant message starts.
message_update Repeats. Carries text, thinking and tool-call deltas.
message_end The assistant message ends.
tool_execution_start One event for each tool call.
tool_execution_end Fires in completion order.
message_start · message_end The toolResult messages. Saved in source order.
turn_end The turn ends. The loop can start another turn.
agent_end The run ends.

Four rules that tests enforce

Parallel tools

tool_execution_end fires in completion order. toolResult messages are saved in source order.
Terminate

The loop skips the next model call only when all finalized tool results set terminate=True.
No raised errors

The stream function never raises. A failure becomes an error event, with stop_reason set to error or aborted.
Usage

Token usage is the per-field maximum of the reported snapshots, not their sum.

03 Architecture

Small parts with clear borders.

Each layer has one job. You can replace the UI, the model provider or an extension without a change to the loop.

The Python packages use the MIT license. zypi is a fork of grok-build with all x.ai vendor extensions removed. It keeps the Apache-2.0 license.

zypi

The terminal UI. It draws the screen and talks ACP.

Rust · Apache-2.0

Zed and other ACP clients

Editors. They start the same agent process.

ACP over stdio

pi_agent_cli

The ACP agent. System prompt engine, permissions, project trust and headless mode.

Python · MIT

pi_agent_harness

Sessions, compaction, skills, prompt templates and the local execution environment.

Python · MIT

pi_agent_core

The agent loop, the event protocol, tool execution and the coding tools.

Python · MIT

HTTPS

LangChain stream function

OpenAI, Anthropic, DeepSeek or any OpenAI-compatible gateway.

04 Features

What you get today.

This list shows what the code does now. It does not show plans.

Seven coding tools

read, edit, write, bash, grep, find and ls. When the agent cuts an output, a notice tells the model how to read the rest.
Sessions that you can resume

Use /new and /resume in the UI, or zypi --continue on the command line. Compaction keeps a long session inside the context window.
Headless mode

Run python -m pi_agent_cli -p "prompt" in scripts and CI. If the model call fails, it prints the error to stderr and exits with status 1.
Skills and context files

The agent reads AGENTS.md and CLAUDE.md context files. It lists your skills in the system prompt.
Extensions in Python

Web search and fetch, goal planning, workflows and MCP ship as separate packages. You can write your own with the extension API.
Workflows in a child process

Workflow scripts run in a child process with operating-system limits. The limits are the boundary. The audit hook is only a speed bump.
Limits that you can set

Set max_turns, a timeout for each tool, and retries before the first token. Hooks run before and after each model call.
Thinking and cost

Reasoning parameters map to each provider. Thinking streams as events. The agent tracks token usage and cost for each run.

05 Install

Install it, then pick a model.

Install the Python agent first. Then add the terminal UI, or connect your editor.

Terminal UI (zypi)

bash

# 1. Install the agent, then choose a provider, a model and a key
pip install pi-agent-cli-lc
python -m pi_agent_cli --setup

# 2. Install the terminal UI (Linux x86_64)
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/

# 3. Start it in your project
zypi

The Linux binary needs glibc 2.39 or newer (Ubuntu 24.04 or later).
On macOS with Apple silicon, use the file zypi-macos-arm64. CI builds it. A person has not run it yet. It is not signed.
On Windows, build zypi from source and run it in WSL2. The Python agent runs on Windows.

Zed (custom agent)

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": {}
    }
  }
}

Install uv first. The agent is not in the Zed ACP registry, so add it as a custom agent.
Run --setup once in a terminal, or put the model in ~/.pi-python/agent.toml.
Use [openai] or [anthropic] instead of [deepseek] for those providers.

Headless (scripts and CI)

bash

pip install pi-agent-cli-lc

# One prompt, no UI
python -m pi_agent_cli -p "Explain this codebase" --cwd /path/to/project

# No model, no key: a scripted test double
PI_USE_MOCK=1 python -m pi_agent_cli -p "hello" --cwd .

A failed model call prints error: <reason> to stderr and exits with status 1.
Headless runs never ask a question. They use an answer that you gave before about project trust.

Python library

python

import asyncio
from pi_agent_core import Agent, Model
from pi_agent_core.adapters import langchain_stream


async def main():
    agent = Agent(
        initial_state={
            "system_prompt": "You are a helpful assistant.",
            "model": Model(provider="openai", model_id="gpt-4o-mini"),
        },
        stream_fn=langchain_stream,
    )
    agent.subscribe(lambda event, signal: print(event.type))
    await agent.prompt("Hello!")
    await agent.wait_for_idle()


asyncio.run(main())

Install with pip install "pi-agent-core-lc[openai]". Use [anthropic] or [deepseek] for other providers.
The whole test suite runs without an API key, because it uses a mock stream.

06 Status

The status, as it is.

zycode is in beta. This table shows what is stable and what is not.

Component Status What it does Get it from

pi-agent-core-lc Stable Agent loop, events, tools, LangChain adapter PyPI

pi-agent-harness-lc Stable Sessions, compaction, skills, execution environment PyPI

pi-agent-cli-lc Beta ACP agent and headless mode PyPI

zypi Beta Terminal UI (prebuilt for Linux x86_64) GitHub Releases

pi-web-access-py Beta Web search and fetch PyPI

pi-goal-x-py Beta Goal planning PyPI

pi-dynamic-workflows-py Beta Workflows PyPI

pi-mcp-py Alpha MCP servers that the editor passes PyPI

Next: prebuilt zypi binaries for macOS x86_64 and Windows, and automatic updates.

07 Evidence

We publish how we test, and what went wrong.

We run a benchmark of 30 tasks: 21 from Terminal-Bench and 9 from DeepSWE. The report lists the flaws that we found in our own method.

24 / 30

tasks passed

Latest valid run of each task

How to read this number

One trial for each task. A second run of the same task can give a very different result.
The DeepSWE tasks ran with two turn limits: 60 turns and 100 turns.
Model: DeepSeek-V4-Flash. The DeepSWE reruns used a gateway alias, and we cannot verify the model behind it.
We found two ways for the agent to see the answers. We fixed the first. We published the second as a known issue. We corrected the numbers that they touched.
This is not a leaderboard entry. It is not a like-for-like comparison with other agents.

Read the full report

08 Open source

Read it. Run it. Change it.

The Python packages use the MIT license. zypi is a fork of xai-org/grok-build and keeps the Apache-2.0 license.

Star on GitHub Open an issue Read the changelog

zycode builds on a port of pi-agent-core from the pi project. This is an unofficial project. It is not affiliated with, endorsed by or maintained by the pi project or its maintainers.

A coding agent you can audit.

A written event contract

One protocol, any client

A UI with no model client

Permission by declaration

Project trust

Any model, one loop

One turn with a tool call

Four rules that tests enforce

Parallel tools

Terminate

No raised errors

Usage

zypi

Zed and other ACP clients

pi_agent_cli

pi_agent_harness

pi_agent_core

LangChain stream function

Seven coding tools

Sessions that you can resume

Headless mode

Skills and context files

Extensions in Python

Workflows in a child process

Limits that you can set

Thinking and cost

Terminal UI (zypi)

Zed (custom agent)

Headless (scripts and CI)

Python library

How to read this number

Read it. Run it. Change it.