How homietal/zcode works
ZCode is an AI coding workbench spanning desktop, browser, and terminal experiences. The primary workflow is a user working in a project through one of those interfaces, with backend services and the Agent CLI/runtime providing coding functionality. The repository also includes provider integrations and a dynamic-workflow engine. The README documents the product surfaces and their broad runtime relationships; sampled source confirms selected storage, protocol, and workflow internals, but not every cross-package connection.
Main entry points: zcode-cli Agent CLI and TUI · server HTTP and WS server · web Web client · desktop Desktop app
Components 19
User surfaces
- Desktop app
packages/desktop - Web client
packages/web - Shared UI
packages/ui - Share preview
packages/web/src/share/conversationSharePreviewClient.ts
Backend services
- HTTP and WS server
packages/server - Server launcher
packages/zcode-server-cli/src/main.ts - Business services
packages/services - Shared protocols
packages/shared - RPC framework
packages/rpc
Agent runtime
- Agent CLI and TUI
apps/zcode-cli - Agent bootstrap
apps/zcode-cli/packages/bootstrap/src/app - Workflow engine
apps/zcode-cli/packages/dynamic-workflow/src/engine/engine.ts - Workflow artifacts
apps/zcode-cli/packages/dynamic-workflow/src/engine/engine-artifacts.ts
Integrations and state
- Runtime adapters
apps/zcode-cli/packages/adapters/src - Provider services
packages/provider - Session storage
apps/zcode-cli/packages/adapters/src/storage/session-store/sqlite-session-store.ts - Desktop storage scan
packages/desktop/src/main/resourceManagerStorage.ts - Storage UI hook
packages/ui/src/resource-manager/storage/useStorageUsage.ts
Other components
- Developer
Connections 20
- Developer → Desktop app: uses
README.md - Developer → Web client: uses
README.md - Developer → Agent CLI and TUI: runs
README.md - Desktop app → HTTP and WS server: connects to
- Web client → HTTP and WS server: proxies requests
README.md - Desktop app → Shared UI: presents
- Web client → Shared UI: presents
- Server launcher → HTTP and WS server: starts
- HTTP and WS server → Business services: uses
- Business services → Shared protocols: uses
packages/services/src/zcode-agent/zcodeStorageStartupGate.ts - HTTP and WS server → RPC framework: uses
- Agent CLI and TUI → Agent bootstrap: initializes
apps/zcode-cli/packages/bootstrap/src/app/workspace-hook-review-controller.ts - Agent CLI and TUI → Workflow engine: runs workflows
README.md - Workflow engine → Workflow artifacts: delegates to
apps/zcode-cli/packages/dynamic-workflow/src/engine/engine.ts - Agent CLI and TUI → Runtime adapters: uses
- Agent CLI and TUI → Provider services: calls providers
- Runtime adapters → Session storage: persists sessions
- Desktop storage scan → Business services: creates storage service
packages/desktop/src/main/resourceManagerStorage.ts - Storage UI hook → Desktop storage scan: requests scans
- Web client → Share preview: loads previews
packages/web/src/share/mockConversationSharePreviewClient.ts