{"_id":"@bwndlct/zcode-claw-adapter","name":"@bwndlct/zcode-claw-adapter","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bwndlct/zcode-claw-adapter","version":"0.1.0","description":"Claw Orchestrator custom engine that runs ZCode app-server as the coding session owner, translating Claw stream-json to the ZCode Protocol.","type":"module","license":"MIT","author":{"name":"bwndlct"},"repository":{"type":"git","url":"git+https://github.com/bwndlct/zcode-claw-adapter.git"},"homepage":"https://github.com/bwndlct/zcode-claw-adapter#readme","bugs":{"url":"https://github.com/bwndlct/zcode-claw-adapter/issues"},"keywords":["claw","claw-orchestrator","zcode","app-server","adapter","custom-engine","stream-json"],"bin":{"zcode-claw-adapter":"adapter/bin/zcode-claw-adapter.mjs"},"engines":{"node":">=22"},"scripts":{"check":"node --check adapter/bin/zcode-claw-adapter.mjs && node --check adapter/bin/zcode-app-server.mjs && node --check adapter/lib/zcode-client.mjs && node --check adapter/lib/state.mjs && node --check scripts/install-local.mjs","test":"node --test --test-timeout=60000 --test-force-exit \"test/*.test.mjs\"","install:local":"node scripts/install-local.mjs"},"gitHead":"24ff9a609f258f129f5771ba1519b615ce994cc5","_id":"@bwndlct/zcode-claw-adapter@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-kHMaHJtQjBGOdylh5+K4NGD/GmQ1JlFZXRSLb3XshDT5KxjZxvI0HvY9e9ZRH3yfocPP2rKOt63joFserXduZQ==","shasum":"9ff9cf69881c778284c696cd4de8871971cd72ac","tarball":"https://registry.npmjs.org/@bwndlct/zcode-claw-adapter/-/zcode-claw-adapter-0.1.0.tgz","fileCount":8,"unpackedSize":64204,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCqa+irpUCXvsSIboNT16dI3wDZSMDPLY3alYJnQ4o2mgIhAJq4P/Xm9hlav0Wzv9GVF7jgkE12iwGvHrIZOUPD+f0V"}]},"_npmUser":{"name":"bwndlct","email":"2787046556@qq.com"},"directories":{},"maintainers":[{"name":"bwndlct","email":"2787046556@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zcode-claw-adapter_0.1.0_1788402667703_0.22083151155956648"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-03T02:31:07.412Z","0.1.0":"2026-09-03T02:31:07.861Z","modified":"2026-09-03T02:31:08.238Z"},"maintainers":[{"name":"bwndlct","email":"2787046556@qq.com"}],"description":"Claw Orchestrator custom engine that runs ZCode app-server as the coding session owner, translating Claw stream-json to the ZCode Protocol.","homepage":"https://github.com/bwndlct/zcode-claw-adapter#readme","keywords":["claw","claw-orchestrator","zcode","app-server","adapter","custom-engine","stream-json"],"repository":{"type":"git","url":"git+https://github.com/bwndlct/zcode-claw-adapter.git"},"author":{"name":"bwndlct"},"bugs":{"url":"https://github.com/bwndlct/zcode-claw-adapter/issues"},"license":"MIT","readme":"# zcode-claw-adapter\n\nA [Claw Orchestrator](https://github.com/Enderfga/claw-orchestrator) custom\nengine that lets Claw own orchestration while [ZCode](https://z.ai) owns the\ncoding session. The adapter translates Claw stream-json messages to the ZCode\nProtocol over `zcode app-server --stdio` and preserves the real ZCode\n`sess_...` session ID end-to-end (announced in the init event and stored under\nthe state dir, so a stopped or crashed session can be resumed with\n`--resume`).\n\n## Install\n\n```bash\nnpm install -g @bwndlct/zcode-claw-adapter\n```\n\nRequires Node.js >= 22 and a ZCode installation.\n\n## Verified scope\n\nThe current release has been verified on **macOS** against **ZCode Desktop and\nZCode CLI 0.16.5**. It has not been verified on Linux, Windows, or other ZCode\nversions. Platform-specific behavior (for example the macOS desktop\nsession-list refresh via `zcode://` deeplink) degrades gracefully elsewhere.\n\n## Authentication\n\nThe adapter never reads, logs, or persists credential values; the model\nprovider registry it pushes to the ZCode child references an **environment\nvariable name**, not a value.\n\n- Primary entry: export `ZCODE_APPSERVER_KEY=<api key>` (override the variable\n  name with `--api-key-env`).\n- Optional convenience: when `ZCODE_APPSERVER_KEY` is unset, the CLI reads the\n  first enabled Z.AI provider key from the local ZCode Desktop config\n  (`~/.zcode/v2/config.json`, or `$ZCODE_DESKTOP_CONFIG`). This is a fallback,\n  not a requirement.\n- Opaque alternative: pass a full provider registry JSON on an inherited file\n  descriptor with `--registry-fd <n>`; bytes are forwarded to the child\n  byte-for-byte and never logged.\n\n## ZCode binary discovery\n\nOrder: `--zcode-bin <path>` → `$ZCODE_BIN` → `zcode` on `PATH` →\n`/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs` (macOS).\n\n## Usage\n\n```bash\nzcode-claw-adapter --help\nzcode-claw-adapter --version\n```\n\nThe engine speaks Claude-Code-style stream-json on stdin/stdout, which is what\nClaw's `customEngine` spawns in persistent mode. Engine options include:\n\n- `--workspace <dir>` — workspace for ZCode sessions (default: cwd)\n- `--state-dir <dir>` — adapter state dir (default: `~/.local/state/zcode-claw`)\n- `--resume <sessionId>` — resume a ZCode session by its real `sess_...` id\n- `--model <provider/model>` — default `z/GLM-5.3`; `--base-url` overrides the\n  provider endpoint\n- `--mode plan|build|edit|yolo` — ZCode permission mode; `--readonly` is a\n  shorthand for plan + deny-all permission answers\n- `--max-tool-concurrency <N>` — forwarded verbatim to the zcode child's\n  native `ZCODE_MAX_TOOL_CONCURRENCY` env var (throttles all parallel tool\n  calls, not only sub-agent spawns, as of zcode 0.16.5)\n- `--zcode-arg <arg>` — extra args passed to the zcode child (repeatable)\n- `--event-log <file>` — append redacted protocol events for diagnostics\n\nRun `zcode-claw-adapter --help` for the full list.\n\n### Claw configuration\n\nWith Claw >= 6.3.0, presets in `configs/engines/` can be referenced by id, so\nonce the upstream community preset ships you can select the engine with:\n\n```json\n{\n  \"engine\": \"custom\",\n  \"customEngine\": \"zcode\"\n}\n```\n\nThe preset (`Enderfga/claw-orchestrator` → `configs/engines/zcode.json`) points\n`bin` at the `zcode-claw-adapter` command and honors `ZCODE_CLAW_ADAPTER_BIN`\nfor non-standard install locations. Until the preset ships (or if you prefer\nnot to depend on it), pass an inline `CustomEngineConfig` instead — see Claw's\n`skills/references/multi-engine.md` for the inline shape. Per-task overrides\n(workspace, state dir, concurrency, `--no-desktop-refresh`) go through the\ncustom-engine argument passthrough.\n\n## Troubleshooting\n\n- **`zcode app-server exited unexpectedly`** — the ZCode child died. The real\n  session ID is preserved in the state dir; relaunch with `--resume`.\n- **`no credential found ... ZCODE_APPSERVER_KEY`** — set the key explicitly\n  or verify the ZCode Desktop config fallback path.\n- **resume failed: not found** — ZCode persists a session durably only after\n  its first completed turn; a session killed before that is not resumable.\n- `--event-log <file>` records redacted protocol traffic (capped at 64 MB) to\n  diagnose protocol-level issues.\n\n## Development\n\n```bash\nnpm run check      # syntax check\nnpm test           # unit + fake-app-server integration tests\nnpm run install:local   # deploy the adapter files to ~/.local/share/zcode-claw/adapter\n```\n\nEdit this repository as the source of truth, then rerun\n`npm run install:local`; do not maintain the installed copy directly.\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md","_rev":"1-f0c865ece67aa4e2b933d258293670ef"}