@higherdev/cli 0.1.0 → 0.1.2

package/README.md

@@ -56,30 +56,53 @@ hd ask "why is HD-12 stuck?"
 hd msg HD-12 --to builder "also rename the old column" --interrupt
 ```
 
-`hd plan` runs the **architect** here on your machine, on Codex against your
-ChatGPT subscription. It reads the repo, decides what should be built, files an
-epic, and can tune the platform itself: models, effort, routing notes, prompt
-addenda, conventions, budgets. Creating an epic fires `epic.created`, which the
+`hd plan` runs the **architect** here on your machine, on your ChatGPT
+subscription. It reads the repo, decides what should be built, files an epic,
+and can tune the platform itself: models, effort, routing notes, prompt addenda,
+conventions, budgets. Creating an epic fires `epic.created`, which the
 orchestrator already triggers on, so the handoff needs no glue.
 
 ```bash
-hd connect                                 # ChatGPT OAuth, once per machine
-hd doctor                                  # what a run would cost, before it runs
+hd connect     # ChatGPT OAuth, once per machine
+hd doctor      # what a run would cost, before it runs
+hd plan        # a conversation: type, it answers, keep going
+```
+
+Bare `hd plan` on a terminal is a back-and-forth. Every turn after the first
+continues the same Codex session, so it remembers what you already said. A blank
+line or `/exit` leaves, and `hd plan --resume "..."` picks the thread back up
+later.
+
+Give it a request on the command line instead and it runs one turn and exits,
+which is what a script wants:
+
+```bash
 hd plan "assess the call-intel code and plan what is missing"
 hd plan --read-only "what would you change about the agent lineup?"
-hd plan --resume "split the third ticket, it is too big"
+hd plan --once "file the epic we discussed"
 ```
 
-### The subscription is checked, not assumed
+### How it reaches the model
+
+`hd` calls the ChatGPT backend directly with your subscription credentials and
+runs its own agent loop over its own tools, in process. It does not spawn
+`codex exec`. That matters: a subprocess made Codex's coding agent the brain, so
+it owned the system prompt, it had a shell, and a greeting took twenty seconds.
+Direct, a turn answers in about two, `hd` owns the prompt, there is no shell in
+the path, and text streams as it is written.
 
-The platform runs on subscriptions, never per-token APIs, so `hd plan` **refuses
-to start** unless Codex is signed in through the ChatGPT OAuth flow. It reads
-`~/.codex/auth.json` and distinguishes four states: connected, signed in with an
-API key (which bills per token), signed out, and not installed. `hd connect`
-runs `codex login` for you, which opens the browser and writes the token itself.
-`hd` never sees or stores a Codex credential.
+The credential comes from `~/.codex/auth.json`, because the Codex CLI is what
+performs the browser login. Nothing else about Codex is involved. `hd connect`
+runs that login for you; `hd` never sees or stores the token, and renews the
+session automatically rather than asking you to sign in again.
 
-`--allow-api-billing` overrides the refusal when you actually mean to spend.
+`hd plan` **refuses to start** unless that session is a real ChatGPT one, since
+the platform runs on subscriptions and never per-token APIs. It distinguishes
+connected, signed in with an API key (which bills per token), signed out, and
+not installed. `--allow-api-billing` overrides the refusal when you mean it.
+
+The architect reads code through `list_files`, `read_file`, and `search_code`,
+scoped to the workspace checkout. Read only, no shell, no path escape.
 
 `hd mcp` is the same platform as MCP tools on stdio. `hd plan` attaches it to
 Codex for the invocation, with no global config edit. Attach it to Claude Code or
@@ -90,6 +113,9 @@ hd mcp --list                 # the 24 tools, with what each does
 hd mcp --read-only            # safe to hand to anything
 ```
 
+The architect does not go through MCP: its tools are the same functions, called
+in process. `hd mcp` exists so anything else can reach them.
+
 ## Everything else
 
 ```