Cara Install dan Pakai ZCode, AI Coding Workspace dari Z.ai

Verdict Cepat: ZCode adalah AI coding workspace open source dari Z.ai yang menyatukan desktop app, antarmuka browser, dan terminal Agent dalam satu paket. Cocok untuk developer yang ingin satu lingkungan coding berbasis AI tanpa harus merakit sendiri dari nol. Install lewat pnpm, jalankan dalam tiga mode, dan sesuaikan konfigurasi lewat variabel lingkungan. Saya sudah telusuri dokumentasi resminya dan alurnya cukup rapi untuk ukuran proyek yang masih aktif berkembang.

Banyak tool AI coding yang muncul belakangan ini, tapi sebagian besar hanya berupa CLI atau ekstensi editor. ZCode mengambil pendekatan berbeda: satu repositori yang menyediakan klien desktop (Electron), server backend, Web UI, plus Agent CLI dan runtime. Artinya developer bisa memilih cara kerja yang paling pas tanpa terikat satu antarmuka.

Artikel ini membahas cara install, tiga mode menjalankan ZCode, konfigurasi yang sering dipakai, dan kesalahan umum yang perlu dihindari. Semua perintah merujuk ke dokumentasi resmi repositori zai-org/ZCode.

Apa Itu ZCode?

ZCode adalah AI programming workspace yang menyediakan desktop application, browser interface, dan terminal Agent. Repositorinya memuat klien, backend services, shared UI, serta source code untuk Agent CLI dan runtime. Proyek ini berada di bawah organisasi zai-org (Z.ai) dan memakai lisensi Apache-2.0. Source code lengkap tersedia di github.com/zai-org/ZCode.

Versi terbaru yang tercatat di README adalah 3.14.3 dengan update pada 23 September. Angka ini penting karena proyek berkembang cepat: struktur direktori dan perintah bootstrap bisa berubah antar versi. Selalu cek README di branch main sebelum mulai install.

Yang membedakan ZCode dari AI coding assistant biasa adalah kelengkapan lapisannya. Developer tidak hanya mendapat Agent CLI, tapi juga desktop Electron untuk workflow lokal, Web UI yang bisa diakses dari browser, dan server backend yang menangani HTTP serta WebSocket. Satu instalasi mencakup semua lapisan itu.

Fitur Utama ZCode yang Perlu Dicatat

Beberapa fitur inti yang layak dipertimbangkan sebelum memutuskan pakai ZCode:

• Tiga antarmuka dalam satu paket. Desktop (Electron), Web (browser), dan terminal (TUI) berbagi backend yang sama. Pindah mode tidak berarti pindah proyek atau konfigurasi.
• Agent CLI dan runtime terintegrasi. Source Agent CLI berada di apps/zcode-cli/ sebagai direktori biasa dalam repositori, bukan submodule Git terpisah. Ini mempermudah modifikasi atau penelusuran cara kerja Agent.
• Dukungan remote via SSH/WSL. ZCode bisa terhubung ke remote workspace. Resource development diambil dari packages/desktop/mock-cdn dan build artifact lokal, lalu diunggah via SFTP ke remote.
• Konfigurasi berbasis variabel lingkungan. Hampir semua perilaku runtime diatur lewat variabel seperti ZCODE_DATA_BASE_DIR dan ZCODE_SERVER_WORKSPACE, bukan file konfigurasi tersembunyi.
• Packaging lintas platform. Desktop bundle mendukung macOS, Windows, dan Linux dengan arsitektur x64 maupun arm64. CLI distribution dikemas sebagai tarball dengan installer shell.

Fitur-fitur ini membuat ZCode lebih dekat ke “coding workstation” daripada sekadar autocomplete AI. Untuk tim yang butuh konsistensi lingkungan antar developer, pendekatan satu repositori ini cukup menarik. Komunitas pengembangnya aktif di Discord.

Sebelum install, penuhi prasyarat versi tool yang cukup spesifik: Git, Node.js 24.14.0, dan pnpm 10.33.2. Proyek mencatat bahwa mise.toml adalah sumber kebenaran untuk versi tool. Jika sistem sudah memakai mise untuk manajemen versi, ikuti angka di sana; jika tidak, pastikan Node.js dan pnpm sesuai sebelum lanjut. Selisih versi mayor sering berujung pada error dependensi yang membingungkan.

Siapkan juga ruang disk yang cukup. Workspace ini monorepo dengan banyak paket: desktop, web, server, UI, services, shared, RPC, client, provider, dan CLI. Proses bootstrap mengunduh dan membangun sebagian besar paket tersebut. Saya sarankan clone ke direktori yang tidak terlalu dalam path-nya, terutama di Windows, karena beberapa tooling build punya batasan panjang path. Direktori seperti ~/projects/zcode sudah cukup aman.

Cara Install ZCode Langkah demi Langkah

Langkah install inti hanya satu perintah, tapi ada beberapa tahap yang berjalan di belakangnya:

1. Clone repositori. Ambil dari GitHub: https://github.com/zai-org/ZCode. Pastikan koneksi stabil karena repositori monorepo cenderung besar.
2. Masuk ke direktori root. Semua perintah development dan packaging dijalankan dari root repositori, bukan dari subdirektori paket.
3. Jalankan bootstrap. Perintah pnpm bootstrap akan menginstall workspace dependencies, menyiapkan runtime assets untuk desktop lokal, lalu menjalankan build:bootstrap.

Perintah pnpm bootstrap secara default melewatkan persiapan remote assets. Ini cocok untuk development desktop lokal. Jika berencana bekerja dengan remote workspace atau ingin memvalidasi distribution assets remote, gunakan pnpm bootstrap:with-remote yang menyiapkan dependensi plus assets lokal dan remote secara berurutan.

Beberapa alternatif perintah setup yang tersedia:

Untuk sebagian besar pengguna yang ingin mencoba di mesin lokal, pnpm bootstrap sudah cukup. Jalankan perintah lain hanya ketika kebutuhan spesifik muncul.

Tiga Mode Menjalankan ZCode

Setelah bootstrap selesai, ZCode bisa dijalankan dalam tiga mode. Pilihan mode tergantung workflow harian.

Baca juga:

Amazon Blokir Meta Muse: Perang Standar Agentic Commerce

Mode Desktop (Electron)

Perintah pnpm dev:desktop adalah pintu masuk utama. Perintah ini menyiapkan local runtime assets, membangun desktop Agent, lalu menjalankan Electron dengan source watcher. Defaultnya setara dengan pnpm dev:desktop:prod yang memakai konfigurasi service production.

Untuk lingkungan testing, gunakan pnpm dev:desktop:test. Jika butuh direktori data development yang terpisah, setel variabel ZCODE_DATA_BASE_DIR:

ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test

Data aplikasi akan tersimpan di subdirektori .zcode/ di dalam direktori basis yang ditentukan. Ini berguna untuk menguji skenario fresh install tanpa mengganggu sesi utama.

Mode Web

Mode ini cocok ketika sedang mengedit source Web atau backend. Perintah pnpm dev:web menjalankan Web development server di http://localhost:5173 dan backend di http://localhost:3030 secara bersamaan. Buka server Web di browser untuk mulai bekerja.

Request /ws dan /api umum di-proxy ke backend lokal. Endpoint /api/v1/oauth/token di-proxy terpisah ke product service yang dikonfigurasi. Untuk mengarahkan backend ke workspace tertentu, setel ZCODE_SERVER_WORKSPACE:

ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web

Setelah mengubah source Agent, jalankan pnpm --filter @zcode/cli... build lalu restart service agar perubahan terbaca.

Mode CLI (Terminal)

Distribution command-line menggabungkan TUI, Web client, dan Agent di balik satu perintah zcode. Tanpa argumen, perintah ini masuk ke terminal UI. Dengan argumen pertama --web, ia meluncurkan mode Web. Argumen lain diteruskan ke Agent CLI yang ada.

# Terminal UI
zcode

# Mode Web
zcode --web

# Tentukan project dan port tanpa membuka browser otomatis
zcode --web --workspace /path/to/project --port 3030 --no-open

Kedua mode berjalan lokal tanpa Electron. Web mode memakai direktori saat ini sebagai workspace, mendengarkan 127.0.0.1, tanpa token authentication secara default, memilih port yang tersedia, dan membuka browser otomatis. Tekan Ctrl+C untuk menghentikan service.

Untuk akses LAN, gunakan --host 0.0.0.0. Ketika mendengarkan alamat non-lokal, ZCode default menghasilkan access token. Gunakan URL lengkap yang tercetak di terminal. Token bisa ditentukan manual lewat --token atau dimatikan dengan --no-token.

Konfigurasi yang Sering Dipakai

Repositori menyediakan .env.example berisi contoh alamat service dan konfigurasi build. Salin ke .env sesuai kebutuhan, lalu taruh override lokal di .env.local. Variabel yang paling sering muncul:

• ZCODE_DATA_BASE_DIR: direktori basis data aplikasi, disimpan di subdirektori .zcode/ di dalamnya.
• ZCODE_SERVER_WORKSPACE: path workspace untuk Web backend.
• ZCODE_BUILTIN_PROVIDER_CONFIG_FILE: path file konfigurasi provider lokal. Jika tidak disetel, ZCode memakai built-in configuration.
• ZCODE_DIST_BASE_URL: URL basis unduhan yang dipakai installer CLI distribution.
• ZCODE_SERVER_AUTH_TOKEN: autentikasi API dan WebSocket ketika HTTP entry Web service dijalankan langsung.

Variabel runtime bisa disetel eksplisit di environment perintah startup. Konfigurasi default yang dikirim bersama klien ada di config/README.md. Untuk development desktop, pilih lingkungan lewat dev:desktop:test atau dev:desktop:prod.

Kapan Pilih ZCode Dibanding Tool Lain

ZCode bukan satu-satunya pilihan di kategori AI coding. Tabel berikut membantu memposisikannya:

ZCode masuk pertimbangan ketika developer butuh lingkungan coding AI yang lengkap dan bisa diutak-atik, bukan sekadar autocomplete. Jika kebutuhan hanya saran kode cepat di editor, ekstensi AI tetap pilihan lebih ringan.

Bagi yang tertarik dengan ekosistem AI coding lebih luas, artikel tentang Grok 4.7 untuk vibe coding dan mengontrol AI coding agent bisa jadi bahan perbandingan. Untuk konteks tool AI di workflow desain, ada bahasan Workflow Canva AI dan 7 AI tools code review untuk GitHub PR.

Kesalahan Umum yang Sering Dilakukan

Beberapa jebakan yang sering muncul saat pertama kali memakai ZCode:

• Melewatkan pengecekan versi Node.js dan pnpm. README mencatat versi spesifik (Node.js 24.14.0, pnpm 10.33.2). Memaksa install dengan versi berbeda sering menghasilkan error dependensi yang sulit dilacak.
• Menjalankan perintah dari subdirektori. Semua perintah development dan packaging harus dijalankan dari root repositori. Menjalankannya dari dalam paket akan gagal karena konteks workspace tidak terbaca.
• Lupa menyiapkan remote assets saat butuh remote. Untuk remote workspace, pnpm bootstrap default tidak cukup. Gunakan pnpm bootstrap:with-remote atau pnpm prepare:remote-assets terlebih dahulu.
• Salah paham soal build:zcode. Perintah ini hanya membuat distribution dan tidak mengganti zcode yang sudah ada di PATH. Jika perintah masih menunjuk ke instalasi lama, cek dengan command -v zcode (macOS/Linux) atau where.exe zcode (Windows).
• Mengabaikan ZCODE_DIST_BASE_URL saat packaging. Packaging CLI distribution wajib menetapkan URL basis unduhan, baik lewat .env, .env.local, variabel proses, atau flag --base-url. URL contoh di dokumentasi hanya placeholder dan harus diganti dengan hosting URL yang sebenarnya.

Menghindari lima kesalahan di atas menghemat banyak waktu troubleshooting di awal. Dokumentasi resmi repositori tetap rujukan utama ketika ada perubahan perilaku antar versi.

Penutup

ZCode menawarkan pendekatan menarik untuk AI coding workspace: tiga antarmuka, backend terintegrasi, dan Agent yang bisa dimodifikasi langsung dari repositori. Setup-nya memang lebih berat daripada ekstensi editor biasa karena monorepo-nya besar dan menuntut versi Node.js serta pnpm yang spesifik. Trade-off ini masuk akal untuk developer yang butuh lingkungan coding AI lengkap dan konsisten.

Saya merekomendasikan mulai dari mode desktop dulu karena paling minim konfigurasi. Mulai dari pnpm bootstrap, coba mode desktop atau Web sesuai workflow, lalu sesuaikan konfigurasi lewat variabel lingkungan. Jika menemukan perubahan perilaku, cek README di branch main karena proyek ini masih aktif merilis versi baru.

Mau berbagi pengalaman? Ceritakan di kolom komentar bagaimana ZCode bekerja di mesin masing-masing, atau bagian mana dari workflow coding yang masih ingin diotomasi dengan AI.