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, driving the Agent through full-lifecycle development tasks with natural-language instructions
• 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: open Model Settings via Manage models at the bottom of the model picker, then add the Base URL and API Key manually

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 (China) and Z.ai (global) 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 doesn't wait for the window to fill up — it reserves output space and a safety buffer in advance:

Trigger point = context window − output reserve (capped at 21,000) − a safety buffer of about 13,000

• The output reserve is the smaller of "Max output tokens" and 21,000, so the combined deduction is normally a fixed ~34K tokens.
• In practice: a 128K window compacts around 94K tokens (~73%), 200K around 166K, 1M around 966K. The smaller the window, the lower the trigger point as a percentage — this is expected.
• The trigger count includes a live estimate of this turn's tool results, so it runs slightly ahead of the meter above the input box — which is why compaction can appear to fire "before the line".

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. There is currently no user-facing switch or threshold for automatic compaction.

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.

12. Switching computers — which config files should I copy?

Copy these to the same locations on the new machine and almost all of your configuration comes with you:

Project-level config (the <project>/.zcode/ directory) travels with the repository — no need to copy it separately.

Do not copy these two files: ~/.zcode/v2/credentials.json (login credentials are encrypted per device and won't decrypt on another machine — just sign in again) and ~/.zcode/v2/telemetry-state.json (contains a device identifier that must not be shared between machines). Session history and logs aren't worth moving either.

13. ~/.zcode/cli/exec is taking up a lot of space — can I delete it?

Yes. It stores terminal command output from past sessions and is currently never cleaned up automatically, so it grows over time. With ZCode fully quit and no background commands running, you can delete the whole directory — ZCode recreates it as needed. The only cost is that command output from historical tasks can no longer be viewed; configuration and session records are unaffected.

14. Where do I find the ZCode version number?

On macOS: menu bar ZCode → About ZCode. On Windows / Linux: title bar Help → About ZCode. The dialog shows the current version, and update-check toasts include it too. There is currently no version entry in Settings.

15. My hand-maintained config.json's mode field stopped working?

The subagent-related config key was renamed from mode to subagent. This is a breaking change: the old key is no longer read and is not migrated automatically. If you edit config.json under ~/.zcode/ directly or generate it with scripts, rename the mode key to subagent. Configuration changed through the Settings UI is unaffected.