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.

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:

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:

┌ 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 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:

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 above and config.

--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.