feat(installer): add ZCode install target - #1898
Open
modoojunko wants to merge 1 commit into
Open
modoojunko wants to merge 1 commit into
modoojunko wants to merge 1 commit into
Conversation
ZCode is a desktop coding agent with an MCP client, an AGENTS.md
instruction surface, and a hooks runner. It is wired the same
three-layer way as Claude Code (MCP entry + prompt hook + instructions
block), with three config differences this target encodes:
- MCP servers live NESTED under mcp.servers in
~/.zcode/cli/config.json (global) or <repo>/.zcode/config.json
(local) — a top-level mcpServers key silently does nothing. Both
scopes auto-connect at session start.
- Server entries carry no type key (verified against ZCode's bundled
servers); install normalizes a hand-copied Claude-style entry with
type: "stdio" down to the verified shape.
- Config-file hooks only run when hooks.enabled is true (plugin hooks
auto-enable the runner; config hooks don't), and hook entries are
process-shaped ({ type: 'process', command, args, timeoutMs }) rather
than Claude's { type: 'command', command: '<string>' }. The
UserPromptSubmit prompt-hook is therefore now offered for ZCode too.
Instructions go to ~/.zcode/AGENTS.md / <repo>/AGENTS.md — ZCode reads
AGENTS.md (user file first, then workspace), so the same conditional
marker block works in both scopes.
The installer orchestrator, bin help text, README, and the target
contract tests are updated; ZCode-specific tests cover the nested MCP
shape, the enabled/process hook shape, sibling-hook preservation,
opt-out round-trip, cross-platform command spelling, and uninstall
surgery (hooks.enabled is deliberately left in place on removal).
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
zcodeas an install target (codegraph install -t zcode,--print-config zcode, multiselect,--target=all/auto), wiring the same three layers Claude Code gets: MCP server entry, theUserPromptSubmitprompt-hook, and the marker-fenced instructions block.Why
ZCode is a desktop coding agent with an MCP client, an
AGENTS.mdinstruction surface, and a hooks runner — butcodegraph installhad no target for it, and a Claude-style MCP snippet pasted into ZCode's config silently does nothing (shape mismatch below). All config surfaces described here were verified against a live ZCode install.How ZCode differs from the other JSON targets
MCP servers are nested under
mcp.serversin~/.zcode/cli/config.json(global) /<repo>/.zcode/config.json(local) — not the top-levelmcpServerskey Claude/Cursor use. Both scopes auto-connect at session start.{ "mcp": { "servers": { "codegraph": { "command": "codegraph", "args": ["serve", "--mcp"] } } } }Server entries carry no
typekey. ZCode's bundled servers (node_repl,computer-use) and a verified-working codegraph entry are bare{ command, args }; tolerance fortype: "stdio"is unverified, so install writes the verified shape — and normalizes a hand-copied Claude-style entry down to it.Config-file hooks need
hooks.enabled: true(plugin-contributed hooks auto-enable the hook runner; config-file hooks don't — without the flag the hook is parsed but never fires). Hook entries are also process-shaped —{ type: "process", command, args, timeoutMs }, not Claude's{ type: "command", command: "<shell string>" }— so the platform handling moves from the command string (codegraph.cmd prompt-hook, Windows: UserPromptSubmit hook written as "codegraph prompt-hook" fails in Git Bash (missing .cmd extension) #1466) into the argv array (command: "codegraph.cmd"+args: ["prompt-hook"]). The installer's prompt-hook question is now offered when ZCode is a target, not just Claude.Instructions go to
~/.zcode/AGENTS.md/<repo>/AGENTS.md— ZCode reads AGENTS.md (user scope first, then workspace narrows it), so the same conditional marker block works unmodified in both scopes.Uninstall semantics
Surgical, mirroring the Claude target: only
mcp.servers.codegraphis removed (siblings, plus unrelated top-level keys likeplugins, survive); only process entries matchingcodegraph[.cmd] + args includes "prompt-hook"are dropped, with empty groups/events pruned.hooks.enabledis deliberately left in place on uninstall — its provenance is unknowable and a lingeringenabled: truewith no config-file hooks is inert.Testing
typekey,hooks.enabled+ process-shaped hook, byte-identical re-runs, opt-out round-trip, Claude-style entry normalization, sibling-hook preservation across install/uninstall, cross-platform command spelling, local-scope paths, andprintConfigoutput shape.npx vitest runon the three installer suites: 272 passed;tsc --noEmitclean; fullnpm run buildsucceeds. Live-checkedinstall -t zcode -l global -yagainst an isolated $HOME: all three layers written exactly as documented above.