ZCode Getting Started Tutorial

ZCode is a developer agent development environment launched by Zhipu, also known as the Agentic Development Environment, abbreviated as ADE. Unlike traditional editors, it comes with an AI assistant that can deeply operate on projects, view projects, modify files, execute commands, and sort out code changes.

ZCode can connect AI agents to real projects, completing the entire development workflow of requirement analysis, code modification, testing, code review, and pre-launch checks in one place.

Ordinary AI tools can only generate scattered code snippets. ZCode supports issuing complete development tasks in natural language, making it suitable for users who want to drive development with natural language.

The core of ZCode is not simple chatting, but continuously advancing a complete task around a development goal.

What ZCode Is Good For

ZCode is suitable for development work that requires continuous context. It can read files, understand project structure, execute commands, and provide a summary after changes are complete.

This kind of capability suits real engineering, not just one-off question-and-answer.

Installing ZCode

After entering the official ZCode Chinese website, you can click the download entry on the homepage.

The official website address ishttps://zcode.z.ai/cn。

The official website page shows the currently available download versions, supporting Windows, macOS, and Linux. Usually, the official site shows the download button for the current system:

After downloading, just click to install:

Basic Preparation After Installation

On first launch, you will enter the "First Launch Setup" page. After completing it, click "Connect and Use" in the bottom-left corner to go to the login page:

If you want to use model services, you also need to complete API Key orCoding Planrelated configuration. You can also log in and then configure it on the settings page:

The official free quota is currently very limited and basically not enough. We recommend the following Coding Plan packages:

Next, let's takeByteDance Ark's Coding Planas an example for configuration. Visit ArkCoding Plan event, subscribe to a plan as needed. If usage is low, the Lite version is enough; if usage is very high, you can use the Pro version.

After a successful purchase, clickCreate Your API Key：

Then click the Create button:

Click the small eye icon below to see the API key. When needed, just copy it:

Different tools have different Base URL configurations depending on the compatible protocol:

• Tools compatible with the Anthropic API protocol:https://ark.cn-beijing.volces.com/api/coding
• Tools compatible with the OpenAI API protocol:https://ark.cn-beijing.volces.com/api/coding/v3

Here we choosehttps://ark.cn-beijing.volces.com/api/coding, set the API key to your own. The model list allows adding multiple models. Here fill inKimi-K2.6, you can also add other models such asDeepSeek-V4-Pro：

After adding, you can test whether the model is available:

You can see the added model in the bottom-right corner of the dialog box on the homepage:

ZCode provides pages for API Key configuration, usage statistics, user feedback, and support.

Using ZCode for the First Time

We can start with a simple project, asking ZCode to create a browser-based mini game, or asking it to explain the directory structure of an existing project.

This helps you quickly understand how ZCode works.

Opening or Creating a Workspace

A workspace can be understood as the project directory ZCode is currently processing.

You can open an existing project directory, or start a new project in an empty directory.

ZCode will read files, execute commands, and manage changes within this directory.

Creating a New Task

In ZCode, a task is the basic unit that drives the agent's work.

The official website examples show how to describe tasks using natural language.

The page also displays the new task shortcut.⌘N。

Example of creating a new task:

Create a smart Gomoku web game, including a game board, player moves, win/loss detection, and a simple computer opponent.

Observing the Execution Process

Once a task starts, ZCode analyzes the project based on the goal and proceeds step by step.

You can see task progress, execution logs, file changes, terminal output, and Git status.

This is more reliable than just copying a piece of AI-generated code, because it can put the code back into the real project for verification.

A Complete Beginner Example

Below we use a simple front-end project to demonstrate how to assign tasks to ZCode.

This example does not rely on a backend, making it suitable for beginners to understand the process.

This prompt clearly tells ZCode what to create, which files to use, what features to include, and that the results need to be reported after completion.

The more specific the prompt is, the more likely the Agent's execution will match expectations.

Then a permission prompt will appear; grant the permission and click confirm:

Possible Generated Project Structure

If you run this task in an empty directory, ZCode may create a file structure similar to the one below.

counter-demo/
├── index.html
├── styles.css
└── app.js

You can view the source code:

Source code display effect:

How to Write Good Prompts for ZCode

ZCode can understand natural language, but that doesn't mean shorter prompts are always better.

A good prompt should include goal, scope, constraints, and acceptance criteria.

This allows the Agent to plan and execute more reliably.

Don't just write "help me optimize it." This kind of prompt has too broad a scope, and the Agent will have difficulty determining what you really want.

Common Workflows

ZCode's advantage lies in linking the development process together.

You can take a task from requirement description to code modification, and then to validation and summary.

Creating a Feature from Scratch

When you want to create a new feature, first clarify the boundaries of the feature.

If the project already has a tech stack, also require ZCode to follow the existing conventions.

Understanding Existing Code

When you take over an unfamiliar project, you can first ask ZCode to explain the structure rather than immediately modifying code.

This helps reduce the risk of making unintended changes.

Pre-Commit Checks

Before committing code, you can ask ZCode to review the current changes.

It can help you identify missing files, potential regressions, and missing tests.

Security Confirmation and Permissions

ZCode enters a confirmation flow before critical commands, file modifications, and high-privilege operations. This prevents the Agent from executing dangerous operations without your knowledge.

You can read the confirmation details before executing a command, and then decide whether to allow it.

If you are not sure whether a command is safe, you can first ask ZCode to explain the command's purpose rather than allowing it to run directly.

Common Commands and Inspection Methods

ZCode can use the terminal to run project commands.

The specific commands depend on your project's tech stack.

Below are some commands that appear in official examples and common development scenarios.

$ git status --short
 M src/App.js
 M src/styles.css

The output above indicates that two files have been modified.

Before committing, you should confirm that these changes all match expectations.

Overview of Advanced Capabilities

In addition to desktop task execution, the ZCode documentation also mentions some advanced capabilities.

You don't need to master them all at once in the beginner stage, but you can first understand what problems they solve.

Common Beginner Questions

Below are some common issues you may encounter when first starting to use ZCode.

Will ZCode Automatically Modify My Project Without Permission?

ZCode's critical operations go through a confirmation flow.

You should check the files it will modify and the commands it will run before allowing them.

If you only want it to read the project, you can explicitly write "do not modify files" in the prompt.

Should I Let ZCode Do Many Things at Once?

It is not recommended for beginners to give overly large tasks from the start.

A better approach is to break the task into smaller pieces.

For example, first ask it to understand the project structure, then modify a module, and finally run validation.

What to Do If a Task Fails

First check the terminal output and error messages.

Then ask ZCode to continue fixing based on the errors.

Don't rush to start a completely different task, or you may lose context.

When Is Manual Review Needed?

When business logic, permissions, security, payments, data deletion, or release operations are involved, manual review should be performed.

AI can help identify issues, but the final responsibility still rests with the developer.

Learning Suggestions

The best way to learn ZCode is not to memorize commands, but to practice starting with small tasks.

You can first use it to create a simple page, and then ask it to explain the generated code.

Next, try asking it to fix a small bug, and observe how it reads files, modifies code, and validates results.

Once you are familiar with this task-driven development approach, gradually use capabilities such as code review, release preparation, Remote Control, and Skill.

Treat ZCode as a development partner that can operate on projects, rather than a chatbot that only answers questions. This makes it easier to leverage its value.