cli-relay 1.0.0 → 1.0.2

package/README.md

@@ -6,6 +6,22 @@ Resume-by-reference delegation across codex, agy, claude-code (command-code: fre
 Built 2026-08-16/17, inspired by DeepSeek Harness's subagent architecture but deliberately
 smaller — see design history below before re-deriving any of this from scratch.
 
+## Built for your agent to drive, not just for you to type
+
+cli-relay is designed to be called *by your own coding agent* as a tool, not only typed by
+hand. Every `fresh`/`resume` call returns one structured JSON object on stdout — a native
+session id, the model's answer, exit code, timing/signal info — specifically so an agent can
+parse the result and decide what to do next without guessing at free-form text. Exit codes are
+deliberate and stable (0 success, 1 general error, 2 usage error, 3 "ran but produced no usable
+answer" — see Exit codes below) so an agent's own control flow can branch on them directly.
+
+In practice that means: point your daily-driver agent (Claude Code, Codex, whatever you're
+already using) at this README and ask it to use `cli-relay` to delegate a task to a different
+backend, or to resume a thread from three days ago — it has everything it needs in this file
+and in `cli-relay doctor`'s output to do that itself, without you hand-holding it through the
+CLI's own flags. Nothing about this requires an agent, though — every command works exactly the
+same typed directly into a terminal by hand.
+
 ## Installation
 
 Requires Node.js 18.17 or newer.
@@ -16,6 +32,19 @@ npm install --global cli-relay
 
 The package has no runtime dependencies. Installation exposes the `cli-relay` command.
 
+## Prerequisites
+
+cli-relay routes between AI coding-agent CLIs — it doesn't include or replace them. Install
+whichever of these you actually use (you don't need all four; `cli-relay doctor` after
+installing any of them confirms cli-relay can see it):
+
+- **codex** — `npm install -g @openai/codex`, then `codex login`
+- **claude-code** — `npm install -g @anthropic-ai/claude-code`, then run `claude` once to
+  authenticate
+- **agy** (Google's Antigravity CLI) — macOS: `brew install --cask antigravity-cli`; other
+  platforms: see [antigravity.google/product/antigravity-cli](https://antigravity.google/product/antigravity-cli)
+- **command-code** — `npm install -g command-code`, then `command-code login`
+
 ## Usage
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-relay",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Persistent CLI router for resuming named sessions across AI coding-agent backends.",
   "type": "module",
   "bin": {

package/src/adapters/agy.mjs

@@ -5,6 +5,7 @@ export default {
   name: 'agy',
   order: 20,
   binaryCandidates: ['agy'],
+  installHint: 'macOS: brew install --cask antigravity-cli — other platforms: https://antigravity.google/product/antigravity-cli',
   fresh: (prompt) => [
     'agy', '--dangerously-skip-permissions', '--print-timeout', '10m',
     '--model', 'gemini-3.6-flash-medium', '--add-dir', process.cwd(),

package/src/adapters/claude-code.mjs

@@ -5,6 +5,7 @@ export default {
   name: 'claude-code',
   order: 30,
   binaryCandidates: ['claude'],
+  installHint: 'npm install -g @anthropic-ai/claude-code, then run: claude (once, to authenticate)',
   fresh: (prompt) => [
     'claude', '-p', prompt, '--output-format', 'json', '--dangerously-skip-permissions',
   ],

package/src/adapters/codex.mjs

@@ -20,6 +20,7 @@ export default {
   name: 'codex',
   order: 10,
   binaryCandidates: ['codex'],
+  installHint: 'npm install -g @openai/codex, then: codex login',
   fresh: (prompt) => [
     'codex', 'exec', '--skip-git-repo-check', '--sandbox', 'workspace-write',
     '-m', 'gpt-5.6-sol', '--json', prompt,

package/src/adapters/command-code.mjs

@@ -5,6 +5,7 @@ export default {
   name: 'command-code',
   order: 40,
   binaryCandidates: ['command-code'],
+  installHint: 'npm install -g command-code, then: command-code login',
   fresh: (prompt) => [
     'command-code', '-p', prompt, '-m', 'zai-org/glm-5.2', '--output-format', 'json',
     '--trust', '--no-auto-update',

package/src/commands/doctor.mjs

@@ -53,7 +53,8 @@ export async function cmdDoctor(adapters, isAvailable = realWhichCheck) {
         `${check.adapter.name}: available (found; tried: ${tried}; resolved: ${resolved})`,
       );
     } else {
-      console.log(`${check.adapter.name}: unavailable (not found; tried: ${tried})`);
+      const hint = check.adapter.installHint ? ` — install: ${check.adapter.installHint}` : '';
+      console.log(`${check.adapter.name}: unavailable (not found; tried: ${tried})${hint}`);
     }
   }
 }