Skip to content

feat(installer): add ZCode install target - #1898

Open
modoojunko wants to merge 1 commit into
colbymchenry:mainfrom
modoojunko:feat/zcode-target
Open

modoojunko wants to merge 1 commit into
colbymchenry:mainfrom
modoojunko:feat/zcode-target

Conversation

@modoojunko

Copy link
Copy Markdown

What

Adds zcode as 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, the UserPromptSubmit prompt-hook, and the marker-fenced instructions block.

Why

ZCode is a desktop coding agent with an MCP client, an AGENTS.md instruction surface, and a hooks runner — but codegraph install had 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

  1. MCP servers are nested under mcp.servers in ~/.zcode/cli/config.json (global) / <repo>/.zcode/config.json (local) — not the top-level mcpServers key Claude/Cursor use. Both scopes auto-connect at session start.

    {
      "mcp": {
        "servers": {
          "codegraph": { "command": "codegraph", "args": ["serve", "--mcp"] }
        }
      }
    }
  2. Server entries carry no type key. ZCode's bundled servers (node_repl, computer-use) and a verified-working codegraph entry are bare { command, args }; tolerance for type: "stdio" is unverified, so install writes the verified shape — and normalizes a hand-copied Claude-style entry down to it.

  3. 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.

  4. 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.codegraph is removed (siblings, plus unrelated top-level keys like plugins, survive); only process entries matching codegraph[.cmd] + args includes "prompt-hook" are dropped, with empty groups/events pruned. hooks.enabled is deliberately left in place on uninstall — its provenance is unknowable and a lingering enabled: true with no config-file hooks is inert.

Testing

  • The existing target contract suite covers zcode automatically (install/idempotency/sibling-preservation/uninstall/printConfig); the sibling-preservation case gained a zcode branch for the nested shape.
  • New ZCode-specific tests: nested MCP shape + no type key, 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, and printConfig output shape.
  • npx vitest run on the three installer suites: 272 passed; tsc --noEmit clean; full npm run build succeeds. Live-checked install -t zcode -l global -y against an isolated $HOME: all three layers written exactly as documented above.

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

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant