# Hlix Code

`hlix` with no command opens **Hlix Code**, the interactive coder: a coding agent in your terminal, with every `hlix` command available as a slash command and every file it touches running where you chose.

```bash
hlix                                    # open the shell in this folder
hlix --local                            # …with the agent on this machine
hlix --sandbox docker                   # …in a container, this folder mounted
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 things
hlix -p "what does this repo do" --json  # JSONL events instead of prose
```

It needs a hlix credential and nothing else: the workspace the credential names pays for the model, and `/model` offers only what that workspace serves. There is no model key to paste.

## Flags

- **`--sandbox cloud|docker|local`** — where the agent's files and commands run. Defaults to the project's Coding Workspace when the folder is bound, a container when this machine has one, and this machine otherwise. `--local` is short for `--sandbox local`.
- **`--docker-image <ref>`** — the container image for the `docker` sandbox. Defaults to one carrying git, node and python3.
- **`--harness <name>`** — which coder does the work: `hlix` (ours, the default), `claude-code`, `codex` or `cursor-agent`. An explicit harness this machine cannot run is refused rather than silently swapped.
- **`--project <id>`** — the project to act in, when the folder is not bound to one.
- **`-p`, `--print <prompt>`** — one turn, printed, then exit. Takes the rest of the line, so quoting is optional.
- **`--json`** — with `-p`, one JSON object per line instead of the final text.
- **`--yolo`** — approve every tool without asking. `--allow-writes` is an alias.
- **`--cwd <dir>`** — open the shell on another folder.

The shell needs a terminal. `echo hi | hlix`, `hlix < /dev/null` and `hlix` in a CI step exit `2` with one line pointing at `-p`, rather than starting a session with nothing to read and nowhere to draw.

## The cloud sandbox

`--sandbox cloud` puts the agent's files and commands **inside the project's repository** in its Coding Workspace — the same checkout a task runs against, not the directory above it. A relative path resolves there, `execute_command` runs there, and `git status` shows the project's own working tree.

A change made this way comes back with `hlix pull`:

```bash
hlix --sandbox cloud -p "add a health check to the server" --yolo
hlix status     # cloud: generation 7 available — run `hlix pull`
hlix pull       # the change lands in this folder
```

`hlix status`, `hlix pull` and `hlix push` snapshot whatever the session left uncommitted in the Coding Workspace as one platform-authored commit before answering, so an edit is never stranded there and a push over it reports the conflict rather than quietly winning. A commit you made yourself is left exactly as it is, and the project's `.env` and other protected files never enter one.

A project with no Coding Workspace yet has nothing to code in, and the session says so rather than starting somewhere empty. Running a task in the project builds one, and so does `hlix import` when the project came from a local folder.

## Settings

Six keys, read from `~/.hlix/config.json` and then this folder's `.hlix/config.json`, merged per key — a machine-wide `harness` still applies in a folder whose file only names a `sandbox`. `hlix config list` shows the resolved value, the file it came from, and where it applies; `hlix config set <key> <value>` writes the folder's file and `--global` writes yours.

| key | value | where it applies |
| --- | --- | --- |
| `sandbox` | `cloud`, `docker`, `local` | all sandboxes |
| `harness` | `hlix`, `claude-code`, `codex`, `cursor-agent` | local and docker sandboxes only — a cloud project's coder is the project's own setting, which `/harness` writes |
| `model` | a model id from `/model` | local and docker sandboxes only — a cloud session offers the workspace's models and nothing else |
| `dockerImage` | an image reference | docker sandbox only |
| `memoryTokens` | a number, e.g. `200000` | all sandboxes |
| `yolo` | `true`, `false` | all sandboxes |

## 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` | this session's diagnostic log |
| `/new`, `/threads`, `/resume`, `/compact` | start a conversation, list this project's, pick an earlier one, condense one into memory |
| `/watch` | the project manager's feed, live: decisions, cycles, tasks, its messages — ESC or `q` stops it |
| `/pm <text>` | send the project manager a message; its answer streams into the panel |
| `/follow <task-id>` | one task's status until it is over |
| `/<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, or the command, that is running |
| Ctrl-C twice | leave |

`/harness`, `/sandbox`, `/model` and `/resume` open a picker with the current value marked — arrows and Enter choose, ESC cancels. Given an argument (`/harness codex`) they apply it directly.

Scrolling is your terminal's own: the wheel, PageUp, the scrollbar. An edit shows its change as a diff, a command shows its output and its exit code, and long output collapses with a line saying how much is hidden.

A command gets its panel the moment it starts, not when it ends. A long one — `/import` on a big repository scans every file, walks the history and then uploads — shows a spinner, the seconds it has been running, and its own newest line (`scanning … 5323 files`, `history: 100 commits scanned`, `uploading 12/730 bytes`), each replacing the last rather than stacking. ESC cancels it and the panel says so; a second command is refused while one is running. When a command refuses for a reason it can name — a scan blocked by secrets in the project's history, a folder already imported, no credential — the panel is a short report rather than an error: one line saying what happened, a table of what it found, and the exact command that answers it, which Enter on an empty prompt puts in the composer for you to run or edit. Red is kept for the failures nothing predicted.

It fits the terminal it is in, from a 40-column split pane to an ultrawide, and it follows a resize: the footer drops the segments that no longer fit and says so with an ellipsis rather than keeping the width it started at. Colour is off under `NO_COLOR`, and every signal — a tool, its outcome, a diff line, a warning — carries a glyph as well as a colour, so nothing is lost without it.

## The approval gate

A tool that changes something asks first, as a block directly above the prompt:

```text
┌ Approve  execute_command ───────────────────────────────────────────
│ node --test
→ Allow once      Run execute_command this one time
  Decline         Do not run it; tell the agent why
  Always allow    Allow every execute tool for the rest of this session
```

Reads never ask. `Always allow` grants that family — reads, edits, shell commands, `hlix` calls and MCP tools are separate families, so allowing one never covers another.

`/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. `hlix config set yolo true` makes it a folder's default, `--global` every project's.

**`-p` has nobody to ask:** A headless turn reads freely and **declines** anything that changes something, telling the model to report that rather than hanging on a prompt no one can answer. `--yolo` lets it through.

## What the agent knows about your project

`hlix rules` shows the two instruction files Hlix Code loads, with their sizes; `hlix rules --edit` opens one in `$EDITOR`, creating it with a short header if it does not exist:

- **`~/.hlix/AGENTS.md`** — your own 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 reach the prompt first and the project's second, so the project wins a disagreement. 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`](/cli/environment-discovery/) lists it, and nothing has to be copied or rewritten. Skills load from `.claude/skills`, `.agents/skills`, `.hlix/skills` and `.codex/skills`; a skill whose `name:` is a human title loads under its directory name rather than being refused.

## 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 MCP registrations other editors and agents (Cursor, Gemini, VS Code, Codex and more) already keep 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 — the rest keep working.

**Machine-wide servers are listed, not started:** An MCP server is a process, usually holding a credential, and a machine-wide registration belongs to whatever it was configured for — not to every folder you happen to open. Copy one into `.hlix/mcp.json` to use it in a project.

## Subagents

Three ship with Hlix Code, and the agent chooses between them:

- **`explore`** — read-only investigation. Answers "where is X" or "how does Y work" without filling the conversation with file contents. It has no tool that writes, edits, deletes or runs a command.
- **`plan`** — works out how to make a change and returns the plan: files, edits, order, and how to verify. Changes nothing itself.
- **`execute`** — carries out one self-contained change and verifies it with the project's own command.

Every `.claude/agents/*.md` and `.hlix/agents/*.md` in the folder is registered alongside them. A file claiming one of the three names is skipped, with the reason on the startup line.

A subagent's work renders as one collapsed block — what it was asked, which tools it touched, what it concluded. Ctrl-O opens it.

## In the desktop app

The desktop app's **Terminal** tab is Hlix Code: it opens `hlix --project <id>` in a real terminal inside the app, in your own login shell, with the app's signed-in session handed to it. Nothing to install beyond the CLI itself (`brew install hlix-ai/tap/hlix` or `npm install --global @hlix/cli`), and nothing to log in to twice — `hlix auth status` reports the credential as `session (desktop)`. That session is the app's: it is used for the request and never written to disk, so signing out of the app ends it.

The header switches the same tab to the project's Coding Workspace shell, and offers a local copy of the project (`hlix init --project`, then `hlix pull`) if you want one.

## What it remembers

Memory is **per project**. A session remembers the project it was started in — its conversations, its working notes, and what earlier conversations in it concluded — and nothing from any other folder you run `hlix` in. The startup line names the scope and how much is in it:

```text
memory: project adde1bea… · 3 threads
```

A folder bound to a project (`hlix init`, `hlix import`) is keyed by that project, so a second clone of it shares one memory. An unbound folder is keyed by its own repository root, and the line reads `memory: folder <name>`. Starting in a subdirectory is the same project as starting at the root.

`/threads` and `/resume` list this project's conversations. `/threads --all` also lists conversations kept at the Workspace level; resuming one copies it into this project and leaves the original where it is.

## Where it keeps things

- **Conversations** — `~/.hlix/code/`. A long one is condensed into memory rather than truncated; `hlix config set memoryTokens <n>` sizes that budget.
- **Logs** — `~/.hlix/code/hlix-code.log`. Diagnostic output never reaches the screen; one dim startup line says how much was captured and `/log` reads it.
- **Settings** — the same order of precedence every command uses: `~/.hlix/config.json`, then this folder's `.hlix/config.json`. See [Settings](#settings) above and [`config`](/reference/cli/).

## `--json`, for a script

With `-p --json`, each line is one event:

- `message_start` / `message_update` / `message_end` — `role` and the text so far.
- `tool_start` / `tool_end` — the tool and its call id; `tool_end` carries `isError`, and `denied` when the gate refused it.
- `tool_approval_required` — the tool a turn was asked about.
- `subagent_start` / `subagent_end` — the subagent's type, its task, and how long it took.
- `usage_update` — `totalTokens`, and `costUsd` when the provider reported a price.
- `agent_end` — the last line, with a `reason`. Anything but `complete` exits `1`.