FAQ (Q&A)

This page summarizes answers to common questions about ZCode, including product positioning, pricing, and technical issues you may encounter during use.

1. What is ZCode’s product positioning?

ZCode is a new Agentic Development Environment (ADE). Unlike a traditional IDE that centers manual coding, ZCode puts AI Agents at the center of the workflow. You describe the task in natural language, and the Agent can drive the full loop from coding and debugging to preview and iteration.

• ADE platform: centers on the first-party ZCode Agent, with built-in file management, terminal, Git commit, and live browser preview
• Full-context awareness: Agents can understand project structure, file content, and UI visuals without requiring you to memorize complex command-line flags
• Current focus: strengthening long-task execution and stability around the self-developed ZCode Agent, connecting workspace context, tools, models, permissions, and Review into one continuous development flow

2. Is ZCode free?

The ZCode application itself is completely free. As a developer, you still need your own API Key or a model service plan. Current supported options include:

• Zhipu family: GLM Coding Plan, BigModel resource packages or account balance, and Z.ai
• Model services: model plans and services connected for ZCode Agent
• Enterprise channels: team-managed model channels for ZCode Agent
• Self-hosted services: private model services approved by your team

3. My terminal already has a GLM API configured. Do I still need to configure it again in ZCode?

Yes. Terminal environment variables and the ZCode desktop model setup are separate entry points, so configuration is not synced automatically. You can choose either method:

• Quick Connect: connect a BigModel / Z.ai account from the welcome screen or the avatar menu; if the account has an active plan, it will connect automatically
• Manual setup: add Base URL and API Key through Manage Models

4. Why does Connect keep loading?

If model connection remains in Loading, check both of the following:

1. Network environment: make sure the machine can reach the selected model service
2. Account availability: make sure the signed-in account or API Key has quota and model access

5. How do I give the Agent an entire folder as context?

Either of two ways works.

Pick it with @: the picker in the input box lists both files and folders, and it can also reference skills and agents. Type @ followed by part of the name to filter, then cycle through the candidates with the arrow keys.

Drag it into the input box:

• Drag a folder from the ZCode file tree into the input box.
• Drag a folder from Finder, File Explorer, or another system file manager into the input box.

Either way, ZCode references the folder as context so the Agent can analyze the directory structure and work with files inside it.

6. What is the difference between the Coding Plan endpoint, Anthropic endpoint, and general OpenAI endpoint?

BigModel and Z.ai expose three endpoint types in API Key mode (see Connect Models → BigModel / Z.ai API Endpoints):

Common mistakes:

• Subscribed to Coding Plan but set the OpenAI URL to the general endpoint /api/paas/v4 → plan quota will not work correctly.
• Using only resource packages / balance but filling in the Coding endpoint /api/coding/paas/v4 → the Coding endpoint is for coding scenarios only, not general API usage.
• Connected through Coding Plan account authorization (not API Key) → no manual URL setup needed; ZCode routes automatically.

For Z.ai, replace the host with api.z.ai; the path rules are the same.

7. ZCode won't start on Linux / WSL, login doesn't return to the app, or the input method doesn't work?

On Linux desktops and Windows WSLg, these are the three most common issues, and most cases can be narrowed down quickly:

• AppImage fails to start: usually a missing libfuse2 (on Ubuntu / Debian run sudo apt install libfuse2); if nothing happens when clicking the icon, launch it once from a terminal to see the error; for GPU-related errors, add software-rendering flags such as --disable-gpu.
• Browser login completes but never returns to ZCode: the system handler for zcode:// is usually misconfigured — common causes are launching with sudo, moving the AppImage around login, or installing both the deb package and the AppImage. Check with xdg-mime query default x-scheme-handler/zcode, keep the AppImage at a fixed path, and restart it.
• Only English input works / input method broken: this relates to the IBus / Fcitx5 environment variables of the current session — launch ZCode from a shell where the input method is already configured. The first CJK character not appearing under WSLg is a known compatibility issue; type a placeholder character and delete it as a workaround.

For the full commands, launcher script examples, and the diagnostic info to collect when reporting, see the Linux / WSL Troubleshooting Guide.

8. Context capacity looks smaller than the model's real window. How do I set it for a custom model?

Every model entry carries a context window value, and ZCode computes capacity from it:

• A newly added model, or one without window metadata, defaults to 200,000. That's why a million-token model can still show a 200K capacity after you connect it.
• A model ID ending in [1m] is recognized as a million-token model and is treated as 1,000,000 automatically — no need to type it.
• Otherwise the value you enter wins. Enter 1000000 if you want 1M.

Expand the model under Settings → Model providers to change it. Note that built-in GLM models connected through a Coding Plan use a fixed window that can't be edited; only models you add with an API Key are editable.

The capacity shown for a session comes from the model currently selected in that session, so different sessions in the same project can legitimately show different numbers — an older session keeps the model it was created with.

9. Why does auto-compaction kick in long before the window is full?

Compaction isn't measured against the whole context window but against the effective window = context window − output reserve:

• It triggers when usage reaches 95% of the effective window (keeping roughly a 13,000-token buffer).
• The output reserve defaults to 32,000 tokens. But as soon as you type a value into a model's Advanced → Max output tokens, the reserve becomes exactly that value.

So setting max output to 128,000 removes 128K from the window up front, and compaction arrives far sooner. Leave that field empty unless you have a reason not to — it then follows the model's own limit.

If the window itself is still being treated as the default 200,000 (see the previous entry), early compaction is even more pronounced. Fix the window value first, then re-check the timing.

10. My subagent isn't using the model I configured

Two different cases:

• The built-in general-purpose and Explore agents: you can assign each of them a model in settings. With no override, they inherit the parent session's main model — that's by design. Set a persistent override to pin a model; clear it to go back to inheriting.
• Custom / workspace / plugin subagents: these still follow the model field in their own Markdown file.

So a dispatched subagent running on the parent session's model is the expected result when no override is set — not a fault.

11. The skills list is empty, or global skills don't show up

First check that the skill files are in the right place:

• User level (global): ~/.zcode/skills/<skill-name>/SKILL.md
• Workspace level: <workspace>/.zcode/skills/<skill-name>/SKILL.md

If the directory is empty, there are no global skills to list. Once you've confirmed skills exist there, work through these three steps:

1. In Settings → Skills, browse by source and make sure the search box or source filter isn't hiding them.
2. Newly created or imported skills only appear after you click Refresh.
3. Check the enable toggle on the right of each entry.

For the full directory layout and import options, see Skill.