@hlix/cli 0.4.5 → 0.5.1

package/README.md

@@ -17,7 +17,18 @@ gives you a coding agent with every CLI command available as a slash command,
 and it chooses where that agent's files and shell live: your project's cloud
 Coding Workspace when the folder is bound to hlix, a Docker container when one
 is running, and this machine otherwise. `--sandbox cloud|docker|local` decides
-it yourself; `--local` is short for `--sandbox local`.
+it yourself; `--local` is short for `--sandbox local`. The Docker sandbox runs
+`node:22-bookworm` (git, node, python3 — no bun); `--docker-image <ref>`, or
+`hlix config set dockerImage <ref>`, runs a different one. No official image
+carries all four: `oven/bun`'s Debian variant ships bun alone, and its `node` is
+a symlink to bun rather than Node.js. For a project whose commands need bun,
+`hlix config set dockerImage imbios/bun-node:22-debian` is a community image
+that has git, node, bun and python3 together.
+
+Hlix Code needs no model key of your own. `hlix auth login` is the whole setup:
+the workspace the credential names pays for the coder, and `/model` offers only
+the models that workspace serves. In a `local` or `docker` sandbox you may add
+endpoints of your own — see **Your own model endpoints** below.
 
 Requires Node.js 22.19 or newer.
 
@@ -33,8 +44,8 @@ For CI, and for anything else that must not change underneath you, pin the
 version instead of floating to `latest`:
 
 ```bash
-npm install --global @hlix/cli@0.4.5
-npx @hlix/cli@0.4.5 status --json
+npm install --global @hlix/cli@0.5.1
+npx @hlix/cli@0.5.1 status --json
 ```
 
 ## Authenticate
@@ -110,6 +121,108 @@ key-only dry-run, and approve with `--yes`. Agent instructions, skills, and MCP
 configuration are quarantined for separate review instead of being executed
 during import.
 
+## Hlix Code
+
+```bash
+hlix                                   # open the shell in this folder
+hlix --local                           # …with the agent running on this machine
+hlix --yolo                            # …approving every tool, nothing asks
+hlix -p "write a test for parseArgs"   # one turn, print the answer, exit
+hlix -p "fix the build" --yolo          # …and let that turn change files
+hlix -p "what does this repo do" --json # JSONL events instead of prose
+```
+
+Inside the shell:
+
+| | |
+| --- | --- |
+| `/help` | every command this build knows |
+| `/model` | pick the model, from what your workspace serves |
+| `/harness` | pick which coder does the work |
+| `/sandbox` | pick where this session's files and commands run |
+| `/rules` | which rules files the agent loaded, and how big they are |
+| `/standards` | what this folder gave the agent, and which MCP servers connected |
+| `/yolo` | run without being asked for approval — toggles |
+| `/log` | what this session's libraries logged, which the screen never shows |
+| `/new`, `/threads`, `/resume`, `/compact` | start a conversation, list them, pick an earlier one, condense one into memory |
+| `/<any hlix command>` | `/status`, `/tasks-list`, `/push` — the CLI, inline, as its own panel |
+| `/<your own>` | every `.md` file in `.claude/commands` or `.hlix/commands` |
+| ⇧Tab | switch between `build` and `plan` |
+| Ctrl-O | expand the newest tool, command or subagent panel |
+| ESC | stop the turn that is running |
+| Ctrl-C twice | leave |
+
+A tool that changes something asks first, as a block above the prompt: allow
+once, decline with a reason, or allow that family for the rest of the session.
+`/yolo` turns the asking off for as long as you leave it on, and the footer says
+`yolo` while it is — your "always allow" choices are untouched, so turning it off
+puts you back where you were. `-p` has nobody to ask, so it reads freely and
+declines writes; `--yolo` (older spelling: `--allow-writes`) lets a headless turn
+change things. `hlix config set yolo true` makes it the default for a folder, or
+`--global` for every project.
+
+An edit shows the change as a diff, a command shows its output and its exit code,
+and long output is collapsed with a line saying how much is hidden — Ctrl-O opens
+it. Scrolling is your terminal's own: the wheel, PageUp, the scrollbar.
+
+### What the agent knows about your project
+
+`hlix rules` shows the two instruction files Hlix Code loads, and `hlix rules
+--edit` opens one in `$EDITOR`:
+
+- `~/.hlix/AGENTS.md` — **your** rules, read in every project you open.
+- this project's `AGENTS.md`, else `CLAUDE.md`, else `GEMINI.md` — one of them,
+  the first that exists.
+
+Yours go into the prompt first and the project's second, so the project wins a
+disagreement. Nothing else is duplicated: a repository that keeps `CLAUDE.md` as
+a copy of `AGENTS.md` pays for it once.
+
+Everything other coding agents left in the folder comes too — `hlix standards`
+lists it. Skills load from `.claude/skills`, `.agents/skills`, `.hlix/skills` and
+`.codex/skills`, and a skill whose `name:` is a human title loads under its
+directory name rather than being refused. Subagents come from `.claude/agents`
+and `.hlix/agents`, alongside the three Hlix Code ships: `explore` (read-only),
+`plan` and `execute`.
+
+### MCP servers
+
+A project's MCP servers start with the session and their tools join the agent's.
+They are read from `.mcp.json`, `.hlix/mcp.json`, and the Cursor, Windsurf,
+Gemini, VS Code and Codex registrations already in the folder — `${VAR}`
+placeholders resolve from your environment, so no secret has to live in the file.
+A server that cannot start costs one line in `/standards` and nothing else.
+
+Machine-wide registrations are listed and **not** started: an MCP server is a
+process, usually holding a credential, and it belongs to the project it was
+configured for. Copy one into `.hlix/mcp.json` to use it here.
+
+Conversations are kept in `~/.hlix/code/`, and a long one is condensed into
+memory rather than truncated. `hlix config set memoryTokens <n>` sizes that
+budget (default 200000). Anything the libraries log goes to
+`~/.hlix/code/hlix-code.log` instead of onto the screen; `/log` reads it.
+
+### Your own model endpoints
+
+A `local` or `docker` session can run an OpenAI-compatible endpoint of your own
+alongside the workspace's models. Hlix Code never asks you to paste a key: add
+the endpoint to `~/.hlix/config.json` yourself, and name an environment variable
+rather than writing a secret into the file.
+
+```json
+{
+  "schemaVersion": 1,
+  "providers": [
+    { "name": "lab", "url": "http://localhost:1234/v1", "models": ["qwen3-coder"] },
+    { "name": "acme", "url": "https://api.acme.test/v1", "models": ["acme-coder"],
+      "apiKeyEnv": "ACME_API_KEY" }
+  ]
+}
+```
+
+A **cloud** session ignores them: it runs on the workspace's account, so it
+offers the workspace's models and nothing else.
+
 ## `--json` is a contract
 
 Human output may change at any time. `--json` may not. Every JSON response